Technische documentatie voor integrators

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.

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 resulting token a cookie called access_token:

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

Descriptoin	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

Description	Endpoint	Method	Request Body	Response Body
Get my portoflios	/portfolios	GET		An array of your portfolios. 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; }
Get portfolio by _id.	/portfolios/:_id	GET		An object containing a single portfolio with _id.
Get customers in portfolio by _id.	/portfolios/:_id/customers	GET		An array of the customers a single portfolio with _id. 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; }
	/customers/:_id	GET		An object containing a single customer with _id.
	/customers/:_id	PUT	An object containing a single customer.
	/customers/:_id	POST	An object containing a single customer.

Customers

Get your own portfolios.

Portfolios contain your customers.

Endpoint	Method	Request Body	Response Body
/portfolios/:id/customers	GET		An array of your portfolios. 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; }

Session Requests

Endpoint	Method	Request Body	Response Body
/sessionrequests	POST	SessionRequestCreateObject	{ success: true, ids: string[], }

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,
}