Introduction

Welcome to the Ezus API. Our API follows REST principles, offering a set of HTTP methods that serve as the foundation for Ezus' core functionalities. Its primary purpose is to empower you to programmatically manage your Ezus projects, clients, catalog (suppliers, products, packages), and invoices.

If you're seeking an overview of common use cases achievable through our API, feel free to explore our help center's Integrations section for valuable insights.

For those ready to delve into the details of available methods, you're in the right place. This documentation presents a technical reference for each method in the left-hand section, complemented by code examples in the right-hand section.

While each method possesses its unique specifications, here are some general guidelines:

For any request, you must provide Header Parameters

For GET requests, ensure you also provide the required query parameters

For POST/PUT/DELETE requests, structure your request's body parameters in JSON format (application/json)

Authentication

Principles

Ezus API employs a robust authentication scheme that leverages API Keys and Bearer authentication. To interact with the Ezus API effectively, you'll need two crucial elements:

An Ezus API key
User credentials for an active Ezus account

API key

Ezus uses API keys to control access to its API. To obtain your <YOUR_API_KEY>, kindly request it from your account manager. Every request you make to the Ezus API must include this API key as the x-api-key header parameter, like so:

x-api-key: <YOUR_API_KEY>

Bearer Authentication

Upon successfully calling the /login endpoint with valid credentials, you will receive a bearer token, referred to as <YOUR_TOKEN>. This token remains valid for a duration of 12 hours. The Ezus API requires this bearer token to be included in the Authorization header parameter of all subsequent requests.

Authorization: Bearer <YOUR_TOKEN>

curl --location 'https://api.ezus.app/login' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "<YOUR_EMAIL>",
    "password": "<YOUR_PASSWORD>"
}'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const body = {
  email: "<YOUR_EMAIL>",
  password: "<YOUR_PASSWORD>",
};
const headers = { "x-api-key": "<YOUR_API_KEY>" };

axios.post(baseUrl + "/login", body, headers);

{
  "message": "ok",
  "error": "false",
  "token": "<YOUR_TOKEN>"
}

HTTP Endpoint

POST https://api.ezus.app/login

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key

Body Parameters (application/json)

Parameter	Type	Description
email	String	(Required) Your account email
password	String	(Required) Your account password

Response

A JSON object indicating whether an error occurred during the process, along with the associated message. If successful, it also returns a token that you must retain for future API requests.

Projects

GET project

This API endpoint allows you to retrieve information for a specific project record in Ezus. To do so, you need to specify the project's reference in your query parameter.

curl --location 'https://api.ezus.app/project?reference=project_reference' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.get(baseUrl + "/project?reference=project_reference", headers);

{
  "error": "false",
  "reference": "project_reference",
  "info_title": "Paris fashion week 2024",
  "info_stage": "Confirmed",
  "info_notes": "Jane has verbally confirmed our quotation",
  "info_number": "202306001-P",
  "currency": "€",
  "sales_manager": {
    "email": "travel-design@e-corp.com",
    "first_name": "Alice",
    "last_name": "Tate",
    "agency": "Paris Agency"
  },
  "project_manager": {
    "email": "no-reply@e-corp.com",
    "first_name": "Joe",
    "last_name": "Shmoe",
    "agency": "Paris Agency"
  },
  "alternatives": [
    {
      "alternative_title": "Main Alternative",
      "budget_actual": "88750",
      "trip_budget": "90000",
      "trip_people": "15",
      "trip_date_in": "2024-03-01",
      "trip_date_out": "2024-03-09",
      "trip_duration": "9",
      "trip_destination": "France",
      "trip_subdestination": "Paris",
      "client": {
        "reference": "client_reference",
        "type": "enterprise",
        "company_name": "MOKE INTERNATIONAL LIMITED",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "contact@moke-international.com"
      }
    }
  ],
  "custom_fields": [
    {
      "name": "CustomField",
      "value": "Value"
    }
  ]
}

HTTP Endpoint

GET https://api.ezus.app/project

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Query Parameters

Parameter	Type	Description
reference	String	(Required) The reference of the project you wish to retrieve

Response

A JSON object containing the project information with properties like:

Property	Type	Description
reference	String	The reference of the project
info_title	String	The title of the project
info_stage	String	The stage of the project (Confirmed, Received, Paid...)
info_notes	String	Notes on the project
info_number	String	File number that appears at the bottom of the project record. Not to be confused with reference!
currency	String	Default currency of the project
sales_manager	JSON	JSON object representing the sales manager (User)
project_manager	JSON	JSON object representing the project manager (User)
alternatives	Array	Array of JSON alternatives (Alternatives)
custom_fields	Array	Array of JSON custom fields (Custom fields)

POST projects-upsert

It updates a project record if the provided reference does match one of the project references in your account, otherwise it creates a new project record with the provided reference (or with a random one if no reference is provided).

curl --location 'https://api.ezus.app/projects-upsert' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data-raw '{
    "reference": "project_reference",
    "info_title": "Paris fashion week 2024",
    "info_stage": "Received",
    "trip_budget": "90000",
    "trip_people": "15",
    "trip_date_in": "2023-03-01",
    "trip_date_out": "2023-03-09",
    "sales_manager_email": "travel-design@e-corp.com",
    "client_reference": "client_reference",
    "custom_fields": [
        {"name": "field_name", "value": "field_value" }
    ]
}'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const body = {
  reference: "project_reference",
  info_title: "Paris fashion week 2024",
  info_stage: "Received",
  trip_budget: "90000",
  trip_people: "15",
  trip_date_in: "2023-03-01",
  trip_date_out: "2023-03-09",
  sales_manager_email: "travel-design@e-corp.com",
  client_reference: "client_reference",
  custom_fields: [{ name: "field_name", value: "field_value" }],
};
const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.post(baseUrl + "/projects-upsert", body, headers);

{
  "error": "false",
  "message": "ok",
  "action": "Project successfully created",
  "reference": "project_reference"
}

HTTP Endpoint

POST https://api.ezus.app/projects-upsert

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Body Parameters (application/json)

Parameter	Type	Description
reference	String	If provided, the unique reference associated with the project you want to update or create (or a random one will be generated).
info_title	String	Title of the project. This parameter is required if you create a new project
info_stage	String	Stage of the project: Please use the technical name of the stage you intend to apply. If no specific stage is found, a default stage will be automatically assigned upon adding the project.
trip_budget	Number	Forecasted budget for the project
trip_people	Number	Number of people in the project (only settable when creating a new project)
trip_date_in	Date	Date of the project's start in "YYYY-MM-DD" format (only settable when creating a new project). If not provided or if not formatted correctly, or if duration > 40 days or if trip_date_in > trip_date_out, project will be set as 1 day and trip_date_in as today.
trip_date_out	Date	Date of the project's end in "YYYY-MM-DD" format (only settable when creating a new project). If not provided or if not formatted correctly, or if duration > 40 days or if trip_date_in > trip_date_out, project will be set as 1 day and trip_date_out as today.
sales_manager_email	Email	Email of the Ezus user to be set as the sales manager of the project
client_reference	String	Reference or email of an existing client in your Ezus account to link to the project (only settable when creating a new project)
custom_fields	JSON	Array of JSON custom fields (Custom fields)

Response

A JSON object indicating whether an error occurred during the process, along with the associated message. If successful, it also returns a reference for the project, which you should store for future updates or retrievals.

POST projects-documents-create

This API endpoint enables the creation of a PDF document based on the provided link within the specified project, using the project_reference as its reference.

curl --location 'https://api.ezus.app/projects-documents-create' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
    "project_reference": "project_reference",
    "title": "Document PDF",
    "link": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
}'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const body = {
  project_reference: "project_reference",
  title: "Document PDF",
  link: "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
};
const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.post(baseUrl + "/projects-documents-create", body, headers);

{
  "error": "false",
  "message": "ok"
}

HTTP Endpoint

POST https://api.ezus.app/projects-documents-create

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Body Parameters (application/json)

Parameter	Type	Description
project_reference	String	(Required) The project reference in which you want to create a document
title	String	Title of the document
link	Link	(Required) URL of the document (only supports PDF format and must be publicly accessible)

Response

A JSON object indicating whether an error occurred during the process, along with the associated message.

Clients

GET client

This API endpoint allows you to retrieve information for a specific client record in Ezus. To do so, you need to specify the client's reference in your query parameter.

curl --location 'https://api.ezus.app/client?reference=client_reference' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.get(baseUrl + "/client?reference=client_reference", headers);

{
  "error": "false",
  "reference": "client_reference",
  "type": "enterprise",
  "company_name": "MOKE INTERNATIONAL LIMITED",
  "website": "www.moke_ltd.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "contact@moke-international.com",
  "activity": "Software",
  "vat_number": "GB 240-635-038",
  "siret": "09728676",
  "info_profile": "Prospect",
  "info_origin": "Adwords",
  "info_notes": "This prospect looks interesting to follow",
  "info_number": "202306001-C",
  "user": {
    "email": "tommy@e-corp.com",
    "first_name": "Tommy",
    "last_name": "Atkins",
    "agency": "Paris Agency"
  },
  "address": {
    "label": "58 Rue de Paradis",
    "zip": "75010",
    "city": "Paris",
    "country": "France"
  },
  "projects": {
    "data": [
      {
        "reference": "project_reference",
        "info_title": "Project title"
      }
    ],
    "size": 1
  },
  "contacts": {
    "data": [
      {
        "email": "contact@moke-international.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "title": "CEO",
        "gender": "Ms",
        "phone": "0101010101",
        "phone2": "0606060606",
        "birth_date": "1986-09-17"
      }
    ],
    "size": 1
  },
  "custom_fields": [
    {
      "name": "CustomField",
      "value": "Value"
    }
  ]
}

HTTP Endpoint

GET https://api.ezus.app/client

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Query Parameters

Parameter	Type	Description
reference	String	(Required) The reference of the client you wish to retrieve

Response

A JSON object containing the client information with properties like:

Property	Type	Description
reference	String	The reference of the client
type	String	The type of the client (either "enterprise" or "individual")
company_name	String	Name of the client's company (if applicable)
website	String	Website of the client
first_name	String	First name of the main contact at the client's organization
last_name	String	Last name of the main contact at the client's organization
email	String	Email of the main contact at the client's organization
activity	String	Activity of the client (only for "enterprise" clients)
vat_number	String	VAT number of the client (only for "enterprise" clients)
siret	String	Company registration number of the client (only for "enterprise" clients)
info_profile	String	Profile of the client
info_origin	String	Source of the client
info_notes	String	Notes on the client
info_number	String	File number that appears at the bottom of the client record. Not to be confused with reference!
user	JSON	JSON object representing the user (User) associated with the client
address	JSON	JSON object representing the address (Address) of the client
projects	JSON	Projects linked to the client (returns the first 10 projects)
contacts	Array	An array of JSON contacts (Contacts) associated with the client
custom_fields	Array	An array of JSON custom fields (Custom fields) for the client

POST clients-upsert

This API endpoint allows you to update a client record if the provided reference (or email) matches one of the client references in your account. If no match is found, it creates a new client record with the provided reference (or a random one if no reference is provided). You can use the client's email as the primary key for upserting.

curl --location 'https://api.ezus.app/clients-upsert' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data-raw '{
    "reference": "client_reference",
    "company_name": "MOKE INTERNATIONAL LIMITED",
    "website": "www.moke_ltd.com",
    "user": "sam@proton.me",
    "contact": {
        "email": "contact@moke-international.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "title": "CEO",
        "gender": "Ms",
        "phone": "0101010101",
        "phone2": "0606060606",
        "birth_date": "1986-09-17"
    },
    "address": {
        "label": "58 Rue de Paradis",
        "city": "Paris",
        "country": "France",
        "zip": "75010"
    },
    "custom_fields": [
        {"name": "field_name", "value": "field_value"}
    ]
}'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const body = {
  reference: "client_reference",
  company_name: "MOKE INTERNATIONAL LIMITED",
  website: "www.moke_ltd.com",
  user: "sam@proton.me",
  contact: {
    email: "contact@moke-international.com",
    first_name: "Jane",
    last_name: "Doe",
    title: "CEO",
    gender: "Ms",
    phone: "0101010101",
    phone2: "0606060606",
    birth_date: "1986-09-17",
  },
  address: {
    label: "58 Rue de Paradis",
    city: "Paris",
    country: "France",
    zip: "75010",
  },
  custom_fields: [{ name: "field_name", value: "field_value" }],
};
const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.post(baseUrl + "/clients-upsert", body, headers);

{
  "error": "false",
  "message": "ok",
  "action": "Client successfully created",
  "reference": "client_reference"
}

HTTP Endpoint

POST https://api.ezus.app/clients-upsert

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Body Parameters (application/json)

Parameter	Type	Description
reference	String	If provided, the unique reference associated with the client you want to update or create (or a random one will be generated).
company_name	String	(Required) Name of the client's company (if applicable). If empty, the client will be considered an individual, and the name of the client will be the same as the name of the contact.
website	String	Website of the client
user	Email	Email of the Ezus user to be set as the owner of the client
contact	JSON	A single JSON element (Contacts) representing the main
address	JSON	JSON object address (Address) To reset the address, you can put `'0'`
custom_fields	JSON	Array of JSON custom fields (Custom fields)

Response

Suppliers

GET supplier

This API endpoint allows you to retrieve information for a specific supplier record in Ezus. To do so, you need to specify the supplier's reference in your query parameter.

curl --location 'https://api.ezus.app/supplier?reference=supplier_reference' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.get(baseUrl + "/supplier?reference=supplier_reference", headers);

{
  "error": "false",
  "reference": "supplier_reference",
  "company_name": "The best hotel",
  "website": "www.the_best_hotel.com",
  "capacity": "200",
  "type": "accom, activity",
  "info_notes": "Emily confirmed: this hotel really is the best in town.",
  "info_number": "202306001-S",
  "visual_url": "",
  "user": {
    "email": "travel-design@e-corp.com",
    "first_name": "Alice",
    "last_name": "Tate",
    "agency": "Paris Agency"
  },
  "address": {
    "label": "58 Rue de Paradis",
    "zip": "75010",
    "city": "Paris",
    "country": "France"
  },
  "products": {
    "data": [
      {
        "reference": "product_reference",
        "title": "2-bed room with breakfast"
      }
    ],
    "size": 1
  },
  "contacts": {
    "data": [
      {
        "email": "bob@proton.me",
        "first_name": "Bob",
        "last_name": "Morane",
        "title": "Project Manager",
        "gender": "Mr",
        "phone": "0202020202",
        "phone2": "0707070707"
      }
    ],
    "size": 1
  },
  "medias": {
    "data": [
      {
        "media_name": "The lobby",
        "path_full": "www.the_best_hotel.com/media/loby.jpg"
      }
    ],
    "size": 1
  },
  "langs": [
    {
      "lang": "american",
      "name": "The best hotel",
      "short_description": "The best hotel: Parisian luxury redefined.",
      "long_description": "Welcome to The best hotel, a luxurious Parisian hotel nestled in the heart of the City of Lights. Indulge in timeless elegance, where opulent suites, Michelin-starred dining, and breathtaking views of the Eiffel Tower create an unforgettable experience. Immerse yourself in the rich history and artistry of Paris, while our impeccable service caters to your every desire. Discover the epitome of sophistication at The best hotel where dreams become reality."
    },
    {
      "lang": "spanish",
      "name": "The best hotel",
      "short_description": "Luz y lujo en París: The best hotel.",
      "long_description": "Bienvenido a The best hotel, un lujoso hotel parisino ubicado en el corazón de la Ciudad de las Luces. Disfruta de la elegancia atemporal, donde suites opulentas, gastronomía de estrella Michelin y vistas impresionantes de la Torre Eiffel crean una experiencia inolvidable. Sumérgete en la rica historia y artesanía de París, mientras nuestro servicio impecable atiende cada uno de tus deseos. Descubre la cúspide de la sofisticación en The best hotel donde los sueños se hacen realidad."
    }
  ],
  "custom_fields": [
    {
      "name": "Stars",
      "value": "5"
    }
  ]
}

HTTP Endpoint

GET https://api.ezus.app/supplier

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Query Parameters

Parameter	Type	Description
reference	String	(Required) The reference of the supplier you wish to retrieve

Response

A JSON object containing the supplier information with properties like:

Property	Type	Description
reference	String	The reference of the supplier
company_name	String	Name of the company of the supplier
website	String	Website of the supplier
capacity	String	Maximum number of people for which the supplier can be used
type	String	3 options: `accom`, `activity`, `transport`. A supplier can have no type, 1 type or several types. In this case, the different types are separated by commas
info_notes	String	Notes on the supplier
info_number	String	File number that appears at the bottom of the supplier record. Not to be confused with reference!
visual_url	String	URL of the Google Slides visual linked to the supplier
user	JSON	JSON object user (User)
address	JSON	JSON object address (Address)
products	JSON	JSON object products (Products)
contacts	Array	Array of JSON contacts (Contacts)
medias	JSON	JSON object medias (Medias)
langs	Array	Array of JSON langs (Langs)
custom_fields	Array	Array of JSON custom fields (Custom fields)

POST suppliers-upsert

It updates a supplier record if the provided reference (or the email) does match one of the supplier references in your account, otherwise it creates a new supplier record with the provided reference (or with a random one if no reference is provided). Note that for this endpoint, the email of the supplier can also be used as a primary key for the upsert.

curl --location 'https://api.ezus.app/suppliers-upsert' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data-raw '{
    "reference": "supplier_reference",
    "company_name": "The best hotel",
    "website": "www.the_best_hotel.com",
    "capacity": "200",
    "user": "sam@proton.me",
    "type": "accom, activity",
    "contact": {
        "email": "bob@proton.me",
        "first_name": "Bob",
        "last_name": "Morane",
        "title": "Project Manager",
        "gender": "Mr",
        "phone": "0606060606",
        "phone2": "0707070707",
    },
    "address": {
        "label": "58 Rue de Paradis",
        "city": "Paris",
        "country": "France",
        "zip": "75010"
    },
    "custom_fields": [
        {"name": "field_name", "value": "field_value"}
    ]
}'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const body = {
  reference: "supplier_reference",
  company_name: "The best hotel",
  website: "www.the_best_hotel.com",
  capacity: 200,
  user: "sam@proton.me",
  type: "accom, activity"
  contact: {
    email: "bob@proton.me",
      first_name: "Bob",
      last_name: "Morane",
      title: "Project Manager",
      gender: "Mr",
      phone: "0606060606",
      phone2: "0707070707",
    },
  address: {
    label: "58 Rue de Paradis",
    city: "Paris",
    country: "France",
    zip: "75010",
  },
  custom_fields: [
    { name: "field_name", value: "field_value" }
  ],
};
const headers = { "x-api-key": "<YOUR_API_KEY>", "Authorization": "Bearer <YOUR_TOKEN>" };

axios.post(baseUrl + "/suppliers-upsert", body, headers);

{
  "error": "false",
  "message": "ok",
  "action": "Supplier successfully created",
  "reference": "supplier_reference"
}

HTTP Endpoint

POST https://api.ezus.app/suppliers-upsert

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Body Parameters (application/json)

Parameter	Type	Description
reference	String	If provided, the unique reference associated to the supplier you want to update or create (in case the one you provided has never been used). If no reference is provided, a supplier will be created with a random one.
company_name	String	(Required) Name of the supplier. This parameter is required if you create a new supplier
website	String	Website of the supplier
capacity	Number	Maximum number of people for which the supplier can be used. Leave blank `''` if not relevant
user	Email	Email of the Ezus user that will be set as the owner of the supplier. By default, if no owner is provided or the provided email do not match any user on this account, the owner will be assigned to everyone
type	String	Either `undefined` or a combination of these 3 options: `accom`, `activity`, `transport`. You can select multiple options by separating them with comas ("accom, activity" for instance). Enter "undefined" if you want to reset this parameter.
contact	JSON	Contact is a single JSON and email is needed. Note that only one contact can be upsert this way (the main contact of the supplier) (Contact) To reset the main contact, you can put `'0'`
address	JSON	JSON object address (Address) To reset the address, you can put `'0'`
custom_fields	JSON	Array of JSON custom fields (Custom fields)

Response

Products

GET product

This API endpoint allows you to retrieve information for a specific product record in Ezus. To do so, you need to specify the product's reference in your query parameter.

curl --location 'https://api.ezus.app/product?reference=product_reference' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.get(baseUrl + "/product?reference=product_reference", headers);

{
  "error": "false",
  "reference": "product_reference",
  "title": "2-bed room with breakfast",
  "capacity": "2",
  "quantity": "1",
  "vat_regime": "margin",
  "vat_rate": 20.0,
  "currency": "EUR",
  "budget_text": "Option",
  "budget_form": "Important",
  "budget_variable": "Display",
  "info_number": "202306001-PR",
  "visual_url": "",
  "supplier": {
    "reference": "supplier_reference",
    "company_name": "The best hotel"
  },
  "package": {
    "reference": "package_reference",
    "title": "packages_title"
  },
  "commission": {
    "commission_mode": "purchase",
    "commission_regime": "percent",
    "value": "10"
  },
  "medias": {
    "data": [
      {
        "media_name": "img.jpeg",
        "path_full": "https://link-img.jpeg"
      }
    ],
    "size": 1
  },
  "langs": [
    {
      "lang": "french",
      "name": "Chambre à 2 lits avec petit déjeuner",
      "short_description": "",
      "long_description": ""
    }
  ],
  "tariffs": [
    {
      "reference": "tariff_reference",
      "type": "default",
      "name": "",
      "purchase_price": 100.0,
      "margin_rate": 50.0,
      "sales_price": 200.0,
      "childs": []
    }
  ],
  "custom_fields": [
    {
      "name": "View",
      "value": "Parking"
    }
  ]
}

HTTP Endpoint

GET https://api.ezus.app/product

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Query Parameters

Parameter	Type	Description
reference	String	(Required) The reference of the product you wish to retrieve

Response

A JSON object containing the product information with properties like:

Property	Type	Description
reference	String	The reference of the product
title	String	Name of the product
capacity	Number	Maximum number of people for which the product can be used
quantity	String	The default number for this product when it is added to a project. It can either be a Number or one of these letters (`P` = Number of people in the project, `D` = Number of days in the project, `N` = Number of nights in the project)
vat_regime	String	Can be either `classic` (common law VAT), `margin` (VAT on the margin), `none` (Non applicable VAT)
vat_rate	Number	Default % of the VAT on the product
currency	String	The ISO 4217 currency code representing the currency you utilize (Link to doc)
budget_text	String	This is an empty string `""` if the product is not marked as an option in the budget, otherwise it is the custom label of the option to which the product is associated
buget_form	String	`Important`, `Normal`, `Low` represent how the product will be highlight on the budget By Default
budget_variable	String	`Display`, `Do not Display`, this option tells if the product will be displayed or not in the budget
info_number	String	File number that appears at the bottom of the product record. Not to be confused with reference!
visual_url	String	URL of the Google Slides visual linked to the product
supplier	JSON	A JSON object containing `reference`, `company_name`
package	JSON	A JSON object containing `reference`, `title`
commission	JSON	A JSON object containing `value`, `commission_regime` ("percent" or "amount"), `commission_mode` ("sales" or "purchase")`
medias	JSON	JSON object medias (Medias)
langs	Array	Array of JSON langs (Langs)
tariffs	Array	Array of JSON tariffs (Tariffs)
custom_fields	Array	Array of JSON custom fields (Custom fields)

POST products-upsert

It updates a product record if the provided reference does match one of the product references in your account, otherwise it creates a new product record with the provided reference (or with a random one if no reference is provided).

curl --location 'https://api.ezus.app/products-upsert' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
    "reference": "product_reference",
    "title": "2-bed room with breakfast",
    "quantity": "1",
    "capacity": "2",
    "supplier_reference": "supplier_reference",
    "package_reference": "package_reference",
    "purchase_price": "42",
    "sales_price": "84",
    "vat_regime": "none",
    "vat_rate": 20,
    "currency": "USD",
    "commission": {
        "commission_mode": "purchase",
        "commission_regime": "percent",
        "value": 10
    },
    "custom_fields": [
        {"name": "field_name", "value": "field_value"}
    ]
}'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const body = {
  reference: "product_reference",
  title: "2-bed room with breakfast",
  quantity: "1",
  capacity: 2,
  supplier_reference: "supplier_reference",
  package_reference: "package_reference",
  purchase_price: "42",
  sales_price: "84",
  vat_regime: "none",
  vat_rate: "20",
  currency: "USD",
  commission: {
    commission_mode: "purchase",
    commission_regime: "percent",
    value: "10",
  },
  custom_fields: [{ name: "field_name", value: "field_value" }],
};
const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.post(baseUrl + "/products-upsert", body, headers);

{
  "error": "false",
  "message": "ok",
  "action": "Product successfully created",
  "reference": "product_reference"
}

HTTP Endpoint

POST https://api.ezus.app/products-upsert

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Body Parameters (application/json)

Parameter	Type	Description
reference	String	If provided, the unique reference associated to the product you want to update or create (in case the one you provided has never been used). If no reference is provided, a product will be created with a random one.
title	String	Title of your product. This parameter is required if you create a new product
quantity	String	The default number for this product when it is added to a project. It can either be a Number or one of these letters (`P` = Number of people in the project, `D` = Number of days in the project, `N` = Number of nights in the project)
capacity	Number	Maximum number of people for which the product can be used. Leave blank `''` if not relevant
supplier_reference	String	If you give an adequate supplier reference, the product will be added in this supplier. If you want to update the supplier's product to None, you must enter 0.
package_reference	String	If you give an adequate package reference, the product will be added in this package. If you want to update the package's product to None, you must enter 0.
purchase_price	Number	Purchase price as a number
sales_price	Number	Sales price as a number
vat_regime	String	Can be either `classic` (common law VAT), `margin` (VAT on the margin), `none` (Non applicable VAT). If empty or not provided, your default account VAT regime will be set
vat_rate	Number	Default VAT rate. If empty or not provided, your default account VAT rate will be set
currency	String	The ISO 4217 code of the currency of this product (Link to Doc). If empty or not provided, your default account currency will be set
commission	JSON	A JSON object containing `value`, `commission_regime` ("percent" or "amount"), `commission_mode` ("sales" or "purchase")
custom_fields	JSON	Array of JSON custom fields (Custom fields)

Response

Packages

GET package

This API endpoint allows you to retrieve information for a specific package record in Ezus. To do so, you need to specify the package's reference in your query parameter.

curl --location 'https://api.ezus.app/package?reference=package_reference' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.get(baseUrl + "/package?reference=package_reference", headers);

{
  "error": "false",
  "reference": "package_reference",
  "title": "The best package",
  "capacity": "2",
  "info_notes": "A classical day in Paris",
  "info_number": "202306001-PK",
  "visual_url": "",
  "products": {
    "data": [
      {
        "reference": "product_reference",
        "title": "2-bed room with breakfast"
      },
      {
        "reference": "product_reference_1235",
        "title": "A gourmet menu for 2"
      }
    ],
    "size": 2
  },
  "suppliers": {
    "data": [
      {
        "reference": "supplier_reference",
        "company_name": "The best hotel"
      }
    ],
    "size": 1
  },
  "medias": {
    "data": [],
    "size": 0
  },
  "langs": [
    {
      "lang": "american",
      "name": "The best package",
      "short_description": "A classical day in Paris",
      "long_description": "Immerse yourself in the romance and elegance of a classical Parisian day, as our hotel and restaurant capture the essence of this magical city."
    },
    {
      "lang": "french",
      "name": "Le meilleur package",
      "short_description": "Une journée classique à Paris",
      "long_description": "Plongez dans le romantisme et l'élégance d'une journée parisienne classique, car notre hôtel et notre restaurant capturent l'essence de cette ville magique."
    }
  ],
  "custom_fields": [
    {
      "name": "Is for children?",
      "value": "False"
    }
  ]
}

HTTP Endpoint

GET https://api.ezus.app/package

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Query Parameters

Parameter	Type	Description
reference	String	(Required) The reference of the package you wish to retrieve

Response

A JSON object containing the package information with properties like:

Property	Type	Description
reference	String	The reference of the package
title	String	Name of the package
capacity	String	Maximum number of people for which the package can be used
info_notes	String	Notes on the package
info_number	String	File number that appears at the bottom of the package record. Not to be confused with reference!
visual_url	String	URL of the Google Slides visual linked to the package
products	JSON	JSON object products (Products)
suppliers	JSON	JSON object suppliers (Suppliers)
medias	JSON	JSON object medias (Medias)
langs	Array	Array of JSON langs (Langs)
custom_fields	Array	Array of JSON custom fields Custom fields

POST packages-upsert

It updates a package record if the provided reference does match one of the package references in your account, otherwise it creates a new package record with the provided reference (or with a random one if no reference is provided).

curl --location 'https://api.ezus.app/packages-upsert' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
    "reference": "package_reference",
    "title": "The best package",
    "capacity": "2",
    "custom_fields": [
        {"name": "field_name", "value": "field_value"}
    ]

}'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const body = {
  reference: "package_reference",
  title: "The best package",
  capacity: "2",
  custom_fields: [{ name: "field_name", value: "field_value" }],
};
const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.post(baseUrl + "/packages-upsert", body, headers);

{
  "error": "false",
  "message": "ok",
  "action": "Package successfully created",
  "reference": "package_reference"
}

HTTP Endpoint

POST https://api.ezus.app/packages-upsert

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Body Parameters (application/json)

Parameter	Type	Description
reference	String	If provided, the unique Ezus Reference associated to the package you want to update or create (in case the one you provided has never been used). If no reference is provided, a package will be created with a random one.
title	String	This parameter is required if you create a new package
capacity	Number	Maximum number of people for which the package can be used . Leave blank `''` if not relevant
custom_fields	JSON	Array of JSON custom fields Custom fields

Response

Invoices

GET invoices

It returns a list of your invoices. The invoices are returned sorted by creation date, with the most recent invoices appearing first. You can specify filters as query parameters to narrow down your search. The list of invoices returned is paginated (50 per 50): to call the 50 next items in the list, call the route with the next_token query parameter.

curl --location 'https://api.ezus.app/invoices?stage=completed' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.get(baseUrl + "/invoices?stage=completed", headers);

{
  "error": "false",
  "next_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJtZW51X211bG11bCI6Im9wdDEiLCJudW1iZXIiOiIyMDAwMCIsInBhZ2UiOjEsInBlcnNvX2ludm9pY2UiOiJHRyIsInN0YWdlIjoicGFpZCIsIl9fdGltZSI6MTY5NzQ0NjEzNX0.jEs7aL3UzCNrjzwDtAUbq4Rt4T64nu2LBYC0NnQhHiA",
  "size": 338,
  "data_size": 50,
  "page": 1,
  "invoices": [
    {
      "error": "false",
      "reference": "invoice_reference",
      "info_number": "2023_101010",
      "url": "https://ezus.io/2023_101010.pdf",
      "stage": "completed",
      "type": "credit_note",
      "origin_reference": "origin_reference",
      "origin_info_number": "2023_101009",
      "created_date": "2023-10-10",
      "send_date": "2023-10-10",
      "due_date": "2023-10-10",
      "amount_ttc": 1200.0,
      "amount_ht": 1000.0,
      "vat": 200.0,
      "currency": "EUR",
      "forecast": {
        "is_automatic": true,
        "purchase": 0.0,
        "commission": 0.0,
        "vat_deducted": 0.0,
        "amount_ht": 1000.0
      },
      "actual": {
        "is_automatic": true,
        "purchase": null,
        "commission": null,
        "vat_deducted": null,
        "amount_ht": null
      },
      "project": {
        "reference": "project_reference",
        "info_title": "Paris fashion week 2024",
        "info_stage": "Confirmed",
        "info_number": "202306001-P",
        "currency": "EUR",
        "is_closed": false
      },
      "alternative": {
        "sort_order": "0",
        "title": "Main Alternative"
      },
      "client": {
        "reference": "client_reference",
        "type": "enterprise",
        "company_name": "MOKE INTERNATIONAL LIMITED",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "contact@moke-international.com"
      }
    },...
  ]
}

HTTP Endpoint

GET https://api.ezus.app/invoices

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Query Parameters

Parameter	Type	Description
next_token	String	Specify this parameter if you want to retrieve the following elements of a given list query. If this parameter is filled, other parameters are ignored.
stage	String	You can filter your search only by invoices that are in a specific stage. The stage can be `paid`, `completed` or `draft`.
technical_name	String	You can also filter invoices by one of their custom fields by adding the `technical_name` of the custom field as a query parameter and the desired value as a value.

Response

A JSON object containing the invoice information with properties like:

Property	Type	Description
error	String	false if no errors occurs else true
token	String	A token will be returned if all invoices have not been returned. Use it in another call to access the following invoices
size	Number	The total number of invoices available with these filters
data_size	Number	Number of invoices returned
page	Number	The page number
invoices	Array	An array of JSON containing all the invoices returned formated like GET `invoice` (GET invoice)

GET invoice

This API endpoint allows you to retrieve information for a specific invoice record in Ezus. To do so, you need to specify the invoice's reference in your query parameter.

curl --location 'https://api.ezus.app/invoice?reference=invoice_reference' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.get(baseUrl + "/invoice?reference=invoice_reference", headers);

{
  "error": "false",
  "reference": "invoice_reference",
  "info_number": "2023_101010",
  "url": "https://ezus.io/2023_101010.pdf",
  "stage": "draft",
  "type": "credit_note",
  "origin_reference": "origin_reference",
  "origin_info_number": "2023_101009",
  "created_date": "2023-10-10",
  "send_date": "2023-10-10",
  "due_date": "2023-10-10",
  "amount_ttc": 1200.0,
  "amount_ht": 1000.0,
  "vat": 200.0,
  "currency": "EUR",
  "forecast": {
    "is_automatic": true,
    "purchase": 0.0,
    "commission": 0.0,
    "vat_deducted": 0.0,
    "amount_ht": 1000.0
  },
  "actual": {
    "is_automatic": true,
    "purchase": null,
    "commission": null,
    "vat_deducted": null,
    "amount_ht": null
  },
  "project": {
    "reference": "project_reference",
    "info_title": "Paris fashion week 2024",
    "info_stage": "Confirmed",
    "info_number": "202306001-P",
    "currency": "EUR",
    "is_closed": false
  },
  "alternative": {
    "sort_order": "0",
    "title": "Main Alternative"
  },
  "client": {
    "reference": "client_reference",
    "type": "enterprise",
    "company_name": "MOKE INTERNATIONAL LIMITED",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "contact@moke-international.com"
  }
}

HTTP Endpoint

GET https://api.ezus.app/invoice

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Query Parameters

Parameter	Type	Description
reference	String	(Required) The reference of the invoice you wish to retrieve

Response

A JSON object containing the invoice information with properties like:

Property	Type	Description
reference	String	The reference of the invoice
info_number	String	Title of the invoice
url	String	URL of the invoice `.pdf` file
stage	String	Stage of the invoice `draft` `completed` or `paid`
type	String	Type of the invoice `invoice` or `credit_note`
origin_reference	String	This is only displayed if the type of the invoice is a `credit_note`. The reference of the origin invoice.
origin_info_number	String	This is only displayed if the type of the invoice is a `credit_note`. Title of the origin invoice.
created_date	String	Date of the creation of this invoice, in a "YYYY-MM-DD" format
send_date	String	Sent date of this invoice, in a "YYYY-MM-DD" format
due_date	String	Due date of this invoice, in a "YYYY-MM-DD" format
amount_ttc	Number	Amount of the invoice including taxes
amount_ht	Number	Amount of the invoice excluding taxes
vat	Number	VAT amount of the invoice
currency	String	The ISO 4217 currency code representing the currency you utilize (Link to doc)
forecast	JSON	JSON object forecast (Invoices Amounts)
actual	JSON	JSON object actual (Invoices Amounts)
project	JSON	JSON including: `reference`, `info_title`, `info_stage`, `info_number`, `currency` and `is_closed`
alternative	JSON	JSON including: `sort_order` and `title`
client	JSON	JSON including: `reference`, `type` (enterprise or individual), `company_name`, `first_name`, `last_name` and `email`

PUT invoices-update

It updates an invoice record if the provided reference does match one of the invoices references in your account.

curl --location --request PUT 'https://api.ezus.app/invoices-update' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data-raw '{
    "reference": "invoice_reference",
    "stage": "paid",
    "due_date": "2023-09-29",
    "custom_fields": [
        {"name": "field_name", "value": "field_value"}
    ]
}'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const body = {
  reference: "invoice_reference",
  stage: "paid",
  due_date: "2023-09-29",
  custom_fields: [{ name: "field_name", value: "field_value" }],
};
const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.put(baseUrl + "/invoices-update", body, headers);

{
  "error": "false",
  "message": "ok",
  "reference": "invoice_reference"
}

HTTP Endpoint

PUT https://api.ezus.app/invoices-update

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Body Parameters (application/json)

Parameter	Type	Description
reference	String	The reference of the invoice you want to update
stage	String	stage can be updated only if the invoice is a draft, the stage can be `completed` or `paid`
due_date	String	due_date can be updated only if the invoice is a draft, due_date can be only on format `YYYY-MM-DD`
custom_fields	JSON	Array of JSON custom fields (Custom fields)

Response

GET invoice-supplier

This API endpoint allows you to retrieve information for a specific supplier invoice record in Ezus. To do so, you need to specify the supplier invoice's reference in your query parameter.

curl --location 'https://api.ezus.app/invoice-supplier?reference=invoice_supplier_reference' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.get(
  baseUrl + "/invoice-supplier?reference=invoice_supplier_reference",
  headers
);

{
  "error": "false",
  "reference": "invoice_supplier_reference",
  "url": "https://ezus.io/2023_101010.pdf",
  "created_date": "2023-10-10",
  "due_date": "2023-10-20",
  "amount_ttc": 1200.0,
  "amount_ht": 1000.0,
  "vat": 200.0,
  "currency": "EUR",
  "payments": [
    {
      "date": "2023-10-10",
      "amount": 500.0,
      "payment_method": "Credit Card"
    },
    {
      "date": "2023-10-11",
      "amount": 500.0,
      "payment_method": "Wire"
    },
    {
      "date": "2023-10-12",
      "amount": 200.0,
      "payment_method": "Check"
    }
  ],
  "supplier": {
    "reference": "supplier_reference",
    "company_name": "The best hotel",
    "website": "www.the_best_hotel.com"
  },
  "project": {
    "reference": "project_reference",
    "info_title": "Paris fashion week 2024",
    "info_stage": "Confirmed",
    "info_number": "202306001-P",
    "currency": "EUR",
    "is_closed": false
  },
  "alternative": {
    "sort_order": "0",
    "title": "Main Alternative"
  },
  "client": {
    "reference": "client_reference",
    "type": "enterprise",
    "company_name": "MOKE INTERNATIONAL LIMITED",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "contact@moke-international.com"
  }
}

HTTP Endpoint

GET https://api.ezus.app/invoice-supplier

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Query Parameters

Parameter	Type	Description
reference	String	(Required) The reference of the invoice you wish to retrieve

Response

A JSON object containing the supplier invoice information with properties like:

Property	Type	Description
reference	String	The reference of the supplier invoice
url	String	URL of the supplier invoice file
filename	String	Filename of the supplier invoice
created_date	String	Date of the creation of the supplier invoice, in a "YYYY-MM-DD" format
due_date	String	Due date of the supplier invoice, in a "YYYY-MM-DD" format
amount_ttc	Number	Amount of the supplier invoice excluding taxes
amount_ht	Number	Amount of the supplier invoice including taxes
vat	Number	VAT amount of the supplier invoice
currency	String	The ISO 4217 currency code representing the currency you utilize (Link to doc)
payments	Array	Array of JSON including: `date`, `amount` and `payment_method`
supplier	JSON	JSON including: `reference`, `company_name` and `website`
project	JSON	JSON including: `reference`, `info_title`, `info_stage`, `info_number`, `currency` and `is_closed`
alternative	JSON	JSON including: `sort_order` and `title`
client	JSON	JSON including: `reference`, `type` (enterprise or individual), `company_name`, `first_name`, `last_name` and `email`

Deposits

POST deposits-create

It creates a client deposit in the specified project.

curl --location 'https://api.ezus.app/deposits-create' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data-raw '{
    "project_reference": "project_reference",
    "alternative_order": "0",
    "amount": 6855,
    "type": "deposit",
    "date": "2023-05-25",
    "payment_method": "card",
    "notes": "Up-front payment 2023-05-25",
}'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const body = {
  project_reference: "project_reference",
  alternative_order: "0",
  amount: 6855,
  type: "deposit",
  date: "2023-05-25",
  payment_method: "card",
  notes: "Up-front payment 2023-05-25",
};
const headers = {
  "x-api-key": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.post(baseUrl + "/deposits-create", body, headers);

{
  "error": "false",
  "message": "ok"
}

HTTP Endpoint

POST https://api.ezus.app/deposits-create

Header Parameters

Parameter	Type	Description
x-api-key	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Body Parameters (application/json)

Parameter	Type	Description
project_reference	String	(Required) The reference is mandatory and refers to the project to which the payment will be added.
alternative_order	String	Alternative number, if not entered, the payment will be added to the project's main alternative.
amount	Integer	The deposit amount in cents.
type	String	Type can be `deposit`, `payment`, `final_payment`, `extra_paid`. By default the deposits will be a `deposit`
date	String	The date must be a string in "YYYY-MM-DD" format. If it is not filled in or is invalid, the payment will be assigned to the current date.
payment_method	String	Technical name of the payment method, you can find it in Settings - Custom fields
notes	String	Note attributed to the payment, this note is limited to 100 characters, all additional characters will not be saved.

Response

A JSON object indicating whether an error occurred during the process, along with the associated message.

Webhooks

GET webhooks

Returns a list of your webhook endpoints.

curl --location 'https://api.ezus.app/webhooks' \
--header 'X-API-KEY: <YOUR_API_KEY>' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const headers = {
  "X-API-KEY": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.get(baseUrl + "/webhooks", headers);

{
  "error": "false",
  "webhooks": [
    {
      "reference": "webhook_reference",
      "endpoint": "webhook_endpoint",
      "is_active": "true",
      "events_types": "projects.created,clients.created",
      "last_called_at": "2023-01-01 01:01:01"
    }
  ]
}

HTTP Endpoint

GET https://api.ezus.app/webhooks

Header Parameters

Parameter	Type	Description
X-API-KEY	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Response

An array of JSON that contains your webhooks information.

Property	Type	Description
webhooks	Array	Array of JSON webhooks (Webhooks)

GET webhooks-last

Returns the latest event occurrence of a specified event type.

curl --location 'https://api.ezus.app/webhooks-last?event_type=event_type' \
--header 'X-API-KEY: <YOUR_API_KEY>' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const headers = {
  "X-API-KEY": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.get(baseUrl + "/webhooks-last?event_type=event_type", headers);

{
  "id": "event_id",
  "object": "event",
  "type": "projects.created",
  "created": 1234567890,
  "trigger_reference": "pro.ezus.io;projects-create",
  "is_duplication": false,
  "field": "",
  "old_value": "",
  "new_value": "",
  "data": {...}
}

HTTP Endpoint

GET https://api.ezus.app/webhooks-last

Header Parameters

Parameter	Type	Description
X-API-KEY	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Query Parameters

Parameter	Type	Description
event_type	String	(Required) The event type you wish to retrieve

Response

A JSON object indicating whether an error occurred during the process, along with the associated message. If successful, it returns the latest event occurrence of a specified event type (Events).

POST webhooks-upsert

It updates a webhook record if the provided reference or endpoint does match one of the webhooks in your account, otherwise it creates a new webhook record with the provided reference (or with a random one if no reference is provided).

curl --location 'https://api.ezus.app/webhooks-upsert' \
--header 'X-API-KEY: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
    "reference": "webhook_reference",
    "endpoint": "https://webhook.webhook/",
    "is_active": "true",
    "events_types": "projects.created,clients.created"
}'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const body = {
  reference: "webhook_reference",
  endpoint: "https://webhook.webhook/",
  is_active: "true",
  events_types: "projects.created,clients.created",
};
const headers = {
  "X-API-KEY": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.post(baseUrl + "/webhooks-upsert", body, headers);

{
  "error": "false",
  "message": "ok",
  "action": "Webhook successfully created",
  "reference": "webhook_reference"
}

HTTP Endpoint

POST https://api.ezus.app/webhooks-upsert

Header Parameters

Parameter	Type	Description
X-API-KEY	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Body Parameters (application/json)

Parameter	Type	Description
reference	String	If provided, the unique Ezus Reference associated to the webhook you want to update or create (in case the one you provided has never been used). If no reference is provided, a webhook will be created with a random one.
endpoint	String	If provided, the endpoint associated to the webhook you want to update or create (in case the one you provided has never been used). This parameter is required if you create a new webhook and has to be unique. You cannot update the endpoint of an existing webhook.
is_active	String	Status of the webhook `true` or `false`
events_types	JSON	The list of events to enable for this endpoint. At least 1 required, separated by commas if more than one. (Events)

Response

A JSON object indicating whether an error occurred during the process, along with the associated message. If successful, it also returns a reference for the webhook, which you should store for future updates or retrievals.

DELETE webhooks-delete

It deletes a webhook record if the provided reference or endpoint does match one of the webhooks in your account.

curl --request "DELETE" \
--location 'https://api.ezus.app/webhooks-delete' \
--header 'X-API-KEY: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
    "reference": "webhook_reference",
    "endpoint": "https://webhook.webhook/"
}'

const axios = require("axios");
const baseUrl = "https://api.ezus.app";

const body = {
  reference: "webhook_reference",
  endpoint: "https://webhook.webhook/",
};
const headers = {
  "X-API-KEY": "<YOUR_API_KEY>",
  Authorization: "Bearer <YOUR_TOKEN>",
};

axios.delete(baseUrl + "/webhooks-delete", body, headers);

{
  "error": "false",
  "message": "ok",
  "action": "Webhook successfully deleted"
}

HTTP Endpoint

DELETE https://api.ezus.app/webhooks-delete

Header parameters

Parameter	Type	Description
X-API-KEY	String	(Required) Your Ezus API key
Authorization	String	(Required) Your Bearer token

Body parameters (application/json)

Parameter	Type	Description
reference	String	If provided, the unique Ezus Reference associated to the webhook you want to delete
endpoint	String	If provided, the endpoint associated to the webhook you want to delete

Response

A JSON object indicating whether an error occurred during the process, along with the associated message.

Nested Resources

Address

   "address": {
    "label": "58 Rue de Paradis",
    "zip": "75010",
    "city": "Paris",
    "country": "France"
  },

Property	Type	Description
label	String	Label of the address
city	String	Name of the city
country	String	Name of the country
zip	String	Post code

Alternatives

  "alternatives": [
    {
      "alternative_title": "Main Alternative",
      "budget_actual": "88750",
      "trip_budget": "90000",
      "trip_people": "15",
      "trip_date_in": "2024-03-01",
      "trip_date_out": "2024-03-09",
      "trip_duration": "9",
      "trip_destination": "France",
      "trip_subdestination": "Paris",
      "client": {
        "reference": "client_reference",
        "type": "enterprise",
        "company_name": "MOKE INTERNATIONAL LIMITED",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "contact@moke-international.com"
      }
    }
  ]

Property	Type	Description
alternative_title	String	Title of the alternative
budget_actual	String	Actual budget for the alternative (corresponding to its associated Ezus program)
trip_budget	Number	Forecasted budget for the alternative (the one that is entered manually not the actual one)
trip_people	String	Number of people
trip_date_in	String	Date of the beginning of this alternative, in a "YYYY-MM-DD" format string. If it's empty, the project has no dates
trip_date_out	String	Date of the end of this alternative, in a "YYYY-MM-DD" format string. If it's empty, the project has no dates
trip_duration	String	Number of days this alternative lasts
trip_destination	String	Destination of the alternative
trip_subdestination	String	Subdestination of the alternative
client	JSON	JSON including: `reference`, `type` (enterprise or individual), `company_name`, `first_name`, `last_name` and `email`

Contacts

Only the last 10 contacts are returned in this object. Note that for upsert endpoints, only one contact is required (equivalent to a single JSON element in the contacts.data Array below).

"contacts": {
    "data": [
      {
  "email": "elliot@fsociety.org",
  "first_name": "Elliot",
  "last_name": "Alderson",
  "title": "Developer",
  "gender": "Mr",
  "phone": "",
  "phone2": "",
  "birth_date": "1986-09-17"
  }
    ],
    "size": 1
  }

Property	Type	Description
email	String	Email of the contact
first_name	String	First name of the contact as a string
last_name	String	Last name of the contact as a string
title	String	Title of the contact as a string
gender	String	`Mr`, `Ms` or `Undefined`
phone	String	Phone number of the contact as a string
phone2	String	Second phone number of the contact as a string
birth_date	String	Contact's date of birth in a "YYYY-MM-DD" format string (supplier contacts have no date of birth)

Custom Fields

  "custom_fields": [
    {
      "name": "Text",
      "value": "Value"
    },
    {
      "name": "Number",
      "value": "42"
    },
    {
      "name": "Text area",
      "value": "Value of the text Area"
    },
    {
      "name": "Date",
      "value": "2012-12-21"
    },
    {
      "name": "Time",
      "value": "2006-10-07T12:06:56.568+01:00"
    },
    {
      "name": "URL link",
      "value": "https://urllink.com"
    },
    {
      "name": "File",
      "value": "https://urllink.com/files/document.pdf"
    },
    {
      "name": "Checkbox",
      "value": "true"
    },
    {
      "name": "Dropdown",
      "value": "ExactOption"
    },
    {
      "name": "MultipleDropdown",
      "value": "ExactOption1/-/ExactOption2"
    }
  ]

The technical name of a custom field can be found in the custom field edit modal

Options	Type	Description
Text	String	Simple string like Text Area
Dropdown	String	The option must be written exactly as in the parameters, respecting the case
Multiple Dropdown	String	The option must be written exactly as in the parameters, respecting the case, for Multiple Answer you should enter Option1/-/Option2/-/Option3 in a string, "/-/" should separate each options
Date	String	The date must be in a "YYYY-MM-DD" format string
Time	String	The time must be in a "YYYY-MM-DDTHH:MM:SS+01:00" format string
Checkbox	String	The checkbox must be a string: "true" (checked) OR "false" (unchecked)
Number	String	Number type should be a Number without other character
File	String	File must be a valid URL, and supported file extensions include: .pdf, .jpg, .jpeg, .png, .bmp, .gif, .docx, .doc, .msg, .odt, .rtf, .txt, .ppt, .pptx, .pptm, .csv, .xlsx

Invoices Amounts

"forecast": {
  "is_automatic": true,
  "purchase": 0.0,
  "commission": 0.0,
  "vat_deducted": 0.0,
  "amount_ht": 1000.0
}
"actual": {
  "is_automatic": true,
  "purchase": null,
  "commission": null,
  "vat_deducted": null,
  "amount_ht": null
}

Those objects provides insights into the invoice amounts, differentiating between actual figures and forecasts. Actual figures are available when the associated project is closed and the invoice is marked as completed or paid. Otherwise, null values are displayed.

Property	Type	Description
is_automatic	Boolean	Automatically use the figures of the project to which this invoice/credit_note is linked
purchase	Number	Forecasted / Actual purchase
commission	Number	Forecasted / Actual commission
vat_deducted	Number	Forecasted / Actual deductible VAT
amount_ht	Number	Forecasted / Actual amount excluding taxes

Langs

"langs": [
  {
    "lang": "american",
    "name": "My American product version",
    "short_description": "Short American Description",
    "long_description": "Long American Description"
  }
],

Property	Type	Description
lang	String	Language name in lower case
name	String	Title of the object in this language
short_description	String	Short description of the object in this language
long_description	String	Long description of the object in this language

Medias

Only the last 10 medias are returned in this object.

"medias": {
    "data": [
      {
        "media_name": "img.jpeg",
        "path_full": "https://link-img.jpeg"
      }
    ],
    "size": 1
  }

Property	Type	Description
media_name	String	Title of the media
path_full	String	Media URL. This is a pre-signed URL that expires after 30 minutes

Products

Only the last 10 products are returned in this object.

"products": {
    "data": [
      {
        "reference": "product_reference",
        "title": "2-bed room with breakfast"
      }
    ],
    "size": 1
  }

Property	Type	Description
reference	String	The reference of the product
title	String	The title of the product

Suppliers

Only the last 10 suppliers are returned in this object.

 "suppliers": {
    "data": [
      {
        "reference": "supplier_reference",
        "company_name": "The best hotel"
      }
    ],
    "size": 1
  }

Property	Type	Description
reference	String	The reference of the supplier
company_name	String	The company name of the supplier

Tariffs

  "tariffs": [
    {
      "reference": "tariff_reference",
      "type": "default",
      "name": "",
      "purchase_price": 100.0,
      "margin_rate": 50.0,
      "sales_price": 200.0,
      "childs": []
    }
  ],

Property	Type	Description
reference	String	An unique reference of this tariff
type	String	A tariff can be `default`, `custom` OR `season`.
name	String	Name of the tariff (only season tariffs can have a name)
purchase_price	Number	Purchase price including taxes
margin_rate	Number	The margin rate is based on the sales price
sales_price	Number	Sales price including taxes
childs	Array	Childs are sub-tariffs contained by this tariff (only season tariffs can have childs)

User

One of the following options: None, Everyone, User Group or the following JSON object corresponding to an active Ezus user of this account.

"user": {
    "email": "tommy@e-corp.com",
    "first_name": "Tommy",
    "last_name": "Atkins",
    "agency": "Paris Agency"
}

Property	Type	Description
email	String	Email of the user
first_name	String	First name of the user
last_name	String	Last name of the user
agency	String	User's affiliated agency

Webhooks

"webhooks": [
  {
    "reference": "webhook_reference",
    "endpoint": "webhook_endpoint",
    "is_active": "true",
    "events_types": "projects.created,clients.created",
    "last_called_at": "2023-01-01 01:01:01"
  },
]

Property	Type	Description
reference	String	The reference of the webhook
endpoint	String	The endpoint URL of the webhook
is_active	String	The status of the webhook `true` or `false`
events_types	String	The list of events for this endpoint (Events)
last_called_at	String	The webhook last called date in a "YYYY-MM-DD hh:mm:ss" format string

Events

Basic event information

This section provides an overview of the fundamental details related to a webhook event, including its unique identifier, type, creation timestamp, trigger source, and whether it's a duplication.

{
  "id": "event_id",
  "object": "event",
  "type": "projects.created",
  "created": 1234567890,
  "trigger_reference": "pro.ezus.io;projects-create",
  "is_duplication": false,
  "field": "",
  "old_value": "",
  "new_value": "",
  "data": {...}
}

Property	Type	Description
id	String	Unique identifier for the event
object	String	The object of the event. The event's target object is currently limited to `event` but in the future, webhooks will become capable of being triggered by various other events.
type	String	The type of the event
created	Number	Time at which the object was created. Measured in seconds since the Unix epoch.
trigger_reference	String	The trigger of the event. Indicates the source or origin from which the event was initiated.
is_duplication	Boolean	Indicates whether the event originates from a duplication
field	String	This is only displayed if the event is an update. The name of the field that was updated.
old_value	String	This is only displayed if the event is an update. The previous value of the updated field.
new_value	String	This is only displayed if the event is an update. The updated field's new value.
data	String	Detailed information about the event. For more in-depth details, please refer to the sections below.

projects.created

This event is triggered whenever a project is either created or duplicated.

{
  "data": {
    "reference": "project_reference",
    "info_title": "Paris fashion week 2024",
    "trip_budget": "90000",
    "trip_people": "15",
    "trip_date_in": "2024-03-01",
    "trip_date_out": "2024-03-09",
    "trip_duration": "9",
    "info_number": "202306001-P"
  }
}

Property	Type	Description
reference	String	The reference of the project
info_title	String	The title of the project
trip_budget	String	Forecasted budget for the alternative (the one that is entered manually not the actual one)
trip_people	String	Number of people
trip_date_in	String	Date of the beginning of this alternative, in a "YYYY-MM-DD" format string. If it's empty, the project has no dates.
trip_date_out	String	Date of the end of this alternative, in a "YYYY-MM-DD" format string. If it's empty, the project has no dates.
trip_duration	String	Number of days this project lasts
info_number	String	File number that appears at the bottom of the project record. Not to be confused with reference!

projects.updated

This event is triggered whenever a project is updated. This event is triggered only by specific fields within projects, including: info_title, info_stage, info_notes, info_number, currency, sales_manager, and projects_manager.

{
  "data": {
    "reference": "project_reference",
    "info_title": "Paris fashion week 2024",
    "info_number": "202306001-P"
  }
}

Property	Type	Description
reference	String	The reference of the project
info_title	String	The title of the project
info_number	String	File number that appears at the bottom of the project record. Not to be confused with reference!

clients.created

This event is triggered whenever a client is created.

{
  "data": {
    "reference": "client_reference",
    "type": "enterprise",
    "company_name": "MOKE INTERNATIONAL LIMITED",
    "activity": "Software",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "contact@moke-international.com",
    "gender": "Ms",
    "phone": "0101010101",
    "birth_date": "1986-09-17",
    "info_number": "202306001-C"
  }
}

Property	Type	Description
reference	String	The reference of the client
type	String	The type of the client can be either "enterprise" or "individual"
company_name	String	Name of the company of the client
activity	String	Activity of the client (only for enterprise)
first_name	String	First name of the main contact of the client
last_name	String	Last name of the main contact of the client
email	String	Email of the main contact of the client
gender	String	`Mr`, `Ms` or `Undefined`
phone	String	Phone number of the contact as a string
birth_date	String	Contact's date of birth in a "YYYY-MM-DD" format string
info_number	String	File number that appears at the bottom of the client record. Not to be confused with reference!

clients.updated

This event is triggered whenever a client is updated. This event is triggered only by specific fields within clients, including: company_name, website, activity, vat_number, siret, info_origin, info_notes, info_number and user.

{
  "data": {
    "reference": "client_reference",
    "company_name": "MOKE INTERNATIONAL LIMITED",
    "info_number": "202306001-C"
  }
}

Property	Type	Description
reference	String	The reference of the client
company_name	String	Name of the client's company
info_number	String	File number that appears at the bottom of the client record. Not to be confused with reference!

invoices.finalized

This event is triggered whenever an invoice is finalized (its stage goes from draft to completed).

{
  "data": {
    "reference": "invoice_reference",
    "info_number": "2023_101010",
    "url": "https://ezus.io/2023_101010.pdf",
    "stage": "completed",
    "type": "credit_note",
    "origin_reference": "origin_reference",
    "origin_info_number": "2023_101009",
    "created_date": "2023-10-10",
    "send_date": "2023-10-10",
    "due_date": "2023-10-10",
    "amount_ttc": 1200.0,
    "amount_ht": 1000.0,
    "vat": 200.0,
    "currency": "EUR",
    "project_reference": "project_reference",
    "alternative": {
      "sort_order": "0",
      "title": "Main Alternative"
    }
  }
}

Property	Type	Description
reference	String	The reference of the invoice
info_number	String	Title of the invoice
url	String	URL of the invoice `.pdf` file
stage	String	Stage of the invoice `draft` `completed` or `paid`
type	String	Type of the invoice `invoice` or `credit_note`
origin_reference	String	This is only displayed if the type of the invoice is a `credit_note`. The reference of the origin invoice.
origin_info_number	String	This is only displayed if the type of the invoice is a `credit_note`. Title of the origin invoice.
created_date	String	Date of the creation of this invoice, in a "YYYY-MM-DD" format
send_date	String	Sent date of this invoice, in a "YYYY-MM-DD" format
due_date	String	Due date of this invoice, in a "YYYY-MM-DD" format
amount_ttc	Number	Amount of the invoice including taxes
amount_ht	Number	Amount of the invoice excluding taxes
vat	Number	VAT amount of the invoice
currency	String	The ISO 4217 currency code representing the currency you utilize (Link to doc)
project_reference	String	The reference of the project linked to this invoice
alternative	JSON	JSON including: `sort_order` and `title`

invoices_suppliers.attached

This event is triggered whenever a file is added to a supplier invoice.

{
  "data": {
    "reference": "invoice_supplier_reference",
    "url": "https://ezus.io/2023_101010.pdf",
    "filename": "2023_101010.pdf",
    "created_date": "2023-10-10",
    "due_date": "2023-10-20",
    "amount_ttc": 1200.0,
    "amount_ht": 1000.0,
    "vat": 200.0,
    "currency": "EUR",
    "supplier_reference": "supplier_reference",
    "project_reference": "project_reference",
    "alternative": {
      "sort_order": "0",
      "title": "Main Alternative"
    }
  }
}

Property	Type	Description
reference	String	The reference of the supplier invoice
url	String	URL of the supplier invoice file
filename	String	Filename of the supplier invoice
created_date	String	Date of the creation of this supplier invoice, in a "YYYY-MM-DD" format
due_date	String	Due date of this supplier invoice, in a "YYYY-MM-DD" format
amount_ttc	Number	Amount of the supplier invoice including taxes
amount_ht	Number	Amount of the supplier invoice excluding taxes
vat	Number	VAT amount of the supplier invoice
currency	String	The ISO 4217 currency code representing the currency you utilize (Link to doc)
supplier_reference	String	The reference of the supplier linked to this supplier invoice
project_reference	String	The reference of the project linked to this supplier invoice
alternative	JSON	JSON including: `sort_order` and `title`

Rate Limits

Daily rate limit

For security reasons, the API allows you to make 10,000 calls per day period. What does this "day period" mean? It means we limit to 10,000 requests per day from the first request made. This limit is called later "daily rate limit" and is reset once the day is over.

Burst rate limit

Additionally, the API is protected by a burst rate limit. This means you can't make more than 100 requests per second.

Errors

The Ezus API uses the following error codes:

Error Code	Meaning
200	error="true" error message explained in the "message" string
400	Bad Request -- Your request is invalid.
500	Internal Server Error -- We had a problem with our server. Try again later.

The Ezus API uses the following error messages:

Error Message	Meaning
This <'OBJECT'> has been deleted	The object you try to access has been deleted

Introduction

Authentication

Principles

POST login

HTTP Endpoint

Header Parameters

Body Parameters (application/json)

Response

Projects

GET project

HTTP Endpoint

Header Parameters

Query Parameters

Response

POST projects-upsert

HTTP Endpoint

Header Parameters

Body Parameters (application/json)

Response

POST projects-documents-create

HTTP Endpoint

Header Parameters

Body Parameters (application/json)

Response

Clients

GET client

HTTP Endpoint

Header Parameters

Query Parameters

Response

POST clients-upsert

HTTP Endpoint

Header Parameters

Body Parameters (application/json)

Response

Suppliers

GET supplier

HTTP Endpoint

Header Parameters

Query Parameters

Response

POST suppliers-upsert

HTTP Endpoint

Header Parameters

Body Parameters (application/json)

Response

Products

GET product

HTTP Endpoint

Header Parameters

Query Parameters

Response

POST products-upsert

HTTP Endpoint

Header Parameters

Body Parameters (application/json)

Response

Packages

GET package

HTTP Endpoint

Header Parameters

Query Parameters

Response

POST packages-upsert

HTTP Endpoint

Header Parameters

Body Parameters (application/json)

Response

Invoices

GET invoices

HTTP Endpoint

Header Parameters

Query Parameters

Response

GET invoice

HTTP Endpoint

Header Parameters

Query Parameters

Response

PUT invoices-update