Sidefish Wiki - User contributions [en]

Technische documentatie voor integrators

2022-11-12T16:15:42Z

Dieter: /* Models */

= 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.

[[File:Sidefish-data-sheme.jpg]]

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:<blockquote>[https://sidefish.app/api/v1/users https://sidefish.app/api/v1/] (PRODUCTION)</blockquote><blockquote>[https://sidefish.app/api/v1/users https://staging.sidefish.app/api/v1/users] (STAGING)</blockquote>

== 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.
{| class="wikitable"
|+
!Endpoint
!Method
!Request Body
!Response Body
|-
|/login
|POST
|<syntaxhighlight lang="ts">
{
email: string,
password: string
}
</syntaxhighlight>
|<syntaxhighlight lang="ts">
{
token: string
}
</syntaxhighlight>
|-
|/logout
|POST
|<syntaxhighlight lang="json">
{}
</syntaxhighlight>
|
|}

2. Use the resulting token an auth header with a bearer token: <syntaxhighlight>
authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ....
</syntaxhighlight>

=== 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:<syntaxhighlight lang="http">
cookie: access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....
</syntaxhighlight>

=== 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:<syntaxhighlight lang="http">
x-api-key: 123456789
</syntaxhighlight>

=== 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 ==
{| class="wikitable"
|+
!Description
!Endpoint
!Method
!Request Body
!Response Body
|-
|Get your own user info.
|/users/myuser
|GET
|
|An object containting your user info.<syntaxhighlight lang="typescript">
User: {
_id: "12345789",
...
}
</syntaxhighlight>
|}

=== Models ===
<syntaxhighlight lang="typescript">
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;
}
</syntaxhighlight>

== PORTFOLIOS & CUSTOMERS ==
Your customers are always part of a portfolio.
{| class="wikitable"
!Description
!Endpoint
!Method
!Request Body
!Response Body
|-
|Get my portoflios
|/portfolios
|GET
|
|<syntaxhighlight lang="typescript">
[
Portfolio: {
_id: "12345789",
...
},
]

</syntaxhighlight>
|-
|Get portfolio by _id.
|/portfolios/:_id
|GET
|
|<syntaxhighlight lang="typescript">
Portfolio: {
_id: "12345789",
...
}
</syntaxhighlight>
|-
|Get customers in portfolio by _id.
|/portfolios/:_id/customers
|GET
|
|<syntaxhighlight lang="typescript">
[
Customer: {
_id: "12345789",
...
},
]

</syntaxhighlight>
|-
|Get a single customer by _id.
|/customers/:_id
|GET
|
|<syntaxhighlight lang="typescript">
Customer: {
_id: "12345789",
...
}
</syntaxhighlight>
|-
|Update a single customer by _id.
|/customers/:_id
|PUT
|<syntaxhighlight lang="typescript">
Customer: {
_id: "12345789",
...
}
</syntaxhighlight>
|<syntaxhighlight lang="typescript">
Customer: {
_id: "12345789",
...
}
</syntaxhighlight>
|-
|Create a single customer inside a portfolio.
|/portfolios/:_id/customers
|POST
|<syntaxhighlight lang="typescript">
Customer: {
...
}
</syntaxhighlight>
|<syntaxhighlight lang="typescript">
Customer: {
_id: "12345789",
...
}
</syntaxhighlight>
|}

=== Models ===
<syntaxhighlight lang="typescript">
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;
}

</syntaxhighlight><syntaxhighlight lang="typescript">
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;
}

</syntaxhighlight>

== QUESTIONLISTS ==
There are question lists that can be used in sessionrequests.
{| class="wikitable"
!Description
!Endpoint
!Method
!Request Body
!Response Body
|-
|Get all your questionlists.
|/questionlists
|GET
|
|An object containting your user info.<syntaxhighlight lang="typescript">
[
QuestionList: {
_id: "12345789",
...
},
]
</syntaxhighlight>
|}

=== Models ===
<syntaxhighlight lang="typescript">
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
}

</syntaxhighlight>

== SESSIONREQUESTS ==
A sessionrequest is a request for a customer to complete a questionlist using the Sidefish chat frontend.
{| class="wikitable"
!Description
!Endpoint
!Method
!Request Body
!Response Body
|-
|Create sessionrequests.
|/sessionrequests
|POST
|An object containting your user info.<syntaxhighlight lang="typescript">
[
SessionRequestCreateObject: {
...
},
]
</syntaxhighlight>
|<syntaxhighlight lang="ts">
{
success: true,
ids: string[],
}
</syntaxhighlight>
|}
=== Models ===
<syntaxhighlight lang="typescript">
class SessionRequestCreateObject {
"code": string, // request via /api/v1/sessionrequests/generate-codes/<amount>
"url": string, // example <mijn-kantoor>.sidefish.be/nl/#/<vragenlijst-identifier>/<session-code>
"type": "qlist",
"customer": string, // _id of the customer
"questionList": 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.
}
</syntaxhighlight>

Technische documentatie voor integrators

2022-10-27T14:16:21Z

Dieter: /* C. API KEY */

= Sidefish v5 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.

[[File:Sidefish-data-sheme.jpg]]

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:<blockquote>[https://sidefish.app/api/v1/users https://sidefish.app/api/v1/] (PRODUCTION)</blockquote><blockquote>[https://sidefish.app/api/v1/users https://staging.sidefish.app/api/v1/users] (STAGING)</blockquote>

== 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.
{| class="wikitable"
|+
!Endpoint
!Method
!Request Body
!Response Body
|-
|/login
|POST
|<syntaxhighlight lang="ts">
{
email: string,
password: string
}
</syntaxhighlight>
|<syntaxhighlight lang="ts">
{
token: string
}
</syntaxhighlight>
|-
|/logout
|POST
|<syntaxhighlight lang="json">
{}
</syntaxhighlight>
|
|}

2. Use the resulting token an auth header with a bearer token: <syntaxhighlight>
authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ....
</syntaxhighlight>

=== 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:<syntaxhighlight lang="http">
cookie: access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....
</syntaxhighlight>

=== 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:<syntaxhighlight lang="http">
x-api-key: 123456789
</syntaxhighlight>

=== 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 ==
{| class="wikitable"
|+
!Description
!Endpoint
!Method
!Request Body
!Response Body
|-
|Get your own user info.
|/users/myuser
|GET
|
|An object containting your user info.<syntaxhighlight lang="typescript">
User: {
_id: "12345789",
...
}
</syntaxhighlight>
|}

=== Models ===
<syntaxhighlight lang="typescript">
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;
}
</syntaxhighlight>

== PORTFOLIOS & CUSTOMERS ==
Your customers are always part of a portfolio.
{| class="wikitable"
!Description
!Endpoint
!Method
!Request Body
!Response Body
|-
|Get my portoflios
|/portfolios
|GET
|
|<syntaxhighlight lang="typescript">
[
Portfolio: {
_id: "12345789",
...
},
]

</syntaxhighlight>
|-
|Get portfolio by _id.
|/portfolios/:_id
|GET
|
|<syntaxhighlight lang="typescript">
Portfolio: {
_id: "12345789",
...
}
</syntaxhighlight>
|-
|Get customers in portfolio by _id.
|/portfolios/:_id/customers
|GET
|
|<syntaxhighlight lang="typescript">
[
Customer: {
_id: "12345789",
...
},
]

</syntaxhighlight>
|-
|Get a single customer by _id.
|/customers/:_id
|GET
|
|<syntaxhighlight lang="typescript">
Customer: {
_id: "12345789",
...
}
</syntaxhighlight>
|-
|Update a single customer by _id.
|/customers/:_id
|PUT
|<syntaxhighlight lang="typescript">
Customer: {
_id: "12345789",
...
}
</syntaxhighlight>
|<syntaxhighlight lang="typescript">
Customer: {
_id: "12345789",
...
}
</syntaxhighlight>
|-
|Create a single customer inside a portfolio.
|/portfolios/:_id/customers
|POST
|<syntaxhighlight lang="typescript">
Customer: {
...
}
</syntaxhighlight>
|<syntaxhighlight lang="typescript">
Customer: {
_id: "12345789",
...
}
</syntaxhighlight>
|}

=== Models ===
<syntaxhighlight lang="typescript">
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;
}

</syntaxhighlight><syntaxhighlight lang="typescript">
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;
}

</syntaxhighlight>

== QUESTIONLISTS ==
There are question lists that can be used in sessionrequests.
{| class="wikitable"
!Description
!Endpoint
!Method
!Request Body
!Response Body
|-
|Get all your questionlists.
|/questionlists
|GET
|
|An object containting your user info.<syntaxhighlight lang="typescript">
[
QuestionList: {
_id: "12345789",
...
},
]
</syntaxhighlight>
|}

=== Models ===
<syntaxhighlight lang="typescript">
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
}

</syntaxhighlight>

== SESSIONREQUESTS ==
A sessionrequest is a request for a customer to complete a questionlist using the Sidefish chat frontend.
{| class="wikitable"
!Description
!Endpoint
!Method
!Request Body
!Response Body
|-
|Create sessionrequests.
|/sessionrequests
|POST
|An object containting your user info.<syntaxhighlight lang="typescript">
[
SessionRequestCreateObject: {
...
},
]
</syntaxhighlight>
|<syntaxhighlight lang="ts">
{
success: true,
ids: string[],
}
</syntaxhighlight>
|}
=== Models ===
<syntaxhighlight lang="typescript">
class SessionRequestCreateObject {
"code": string,
"url": string,
"type": "qlist",
"customer": string, // _id
"portfolio": string, // _id
"questionList": string, // _id
"extraFieldsData"?: [{
"extraField": string, // ReportSpec.extraFields[]._id
"value": any,
}],
"notificationSms"?: {
"message"!: string,
"language"?: string,
},
"notificationEmail"?: {
"from"!: string,
"bcc"?: string,
"subject"!: string,
"message"!: string,
"language"?: string,
},
"notificationReminder"?: {
"from"!: string,
"bcc"?: string,
"subject"!: string,
"message"!: string,
"language"?: string,
},
"isNotificationScheduled"?: boolean,
"ccSignedDocuments": undefined | string,
}
</syntaxhighlight>

Technische documentatie voor integrators

2022-10-27T11:23:19Z

Dieter: /* Session Requests */

Technische documentatie voor integrators

2022-10-27T11:19:05Z

Dieter: /* A. Bearer token */

Technische documentatie voor integrators

2022-10-27T11:18:18Z

Dieter:

Technische documentatie voor integrators

2022-10-27T11:16:52Z

Dieter: /* Sessie verzoeken */

Technische documentatie voor integrators

2022-10-27T10:53:40Z

Dieter:

= API Documentatie =

== Authenticatie ==

== Portefeuilles ==

== Klanten ==

== Vragenlijsten ==

== Sessie verzoeken ==

Main Page

2022-10-20T16:04:01Z

Dieter:

Welcome to the Sidefish Wiki! YAY!

Hoezey <syntaxhighlight lang="ts" line="1">
console.log("Hoezey")
</syntaxhighlight>