NAV
cURL javascript

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:

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>

POST login

To initiate authentication, your first step is to make a request to the /login endpoint:

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);

This request returns a structured JSON object:

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

In subsequent requests, remember to replace <YOUR_TOKEN> in the Authorization header parameter with the token you received during this authentication process.

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 projects

It returns a list of your projects. The projects are returned sorted by creation date, with the most recent projects appearing first. The list of projects 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/projects' \
--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 + "/projects", headers);

This request returns a structured JSON object:

{
  "error": "false",
  "next_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJtZW51X211bG11bCI6Im9wdDEiLCJudW1iZXIiOiIyMDAwMCIsInBhZ2UiOjEsInBlcnNvX2ludm9pY2UiOiJHRyIsInN0YWdlIjoicGFpZCIsIl9fdGltZSI6MTY5NzQ0NjEzNX0.jEs7aL3UzCNrjzwDtAUbq4Rt4T64nu2LBYC0NnQhHiA",
  "size": 338,
  "data_size": 50,
  "page": 1,
  "projects": [
    {
      "reference": "project_reference",
      "info_title": "Paris fashion week 2024",
      "info_stage": "Confirmed",
      "info_stage_reference": "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"
      }
    },...
  ]
}

HTTP Endpoint

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

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.
sales_manager String You can filter projects assigned to a specific sales manager. Expected format: email (john.doe@e-corp.com) OR first_name%20last_name (John Doe).
project_manager String You can filter projects assigned to a specific project manager. Expected format: email (john.doe@e-corp.com) OR first_name%20last_name (John Doe).
info_stage_reference String You can filter projects that are in a specific stage. The stage of the project must be indicated by its technical name.

Response

A JSON object containing the project information with properties like:

Property Type Description
next_token String A token will be returned if all projects have not been returned. Use it in another call to access the following projects
size Number The total number of projects available with these filters
data_size Number Number of projects returned on the current page
page Number The page number
projects Array An array of JSON objects, each representing a project. These objects are formatted according to a simplified version of the GET project response structure. (GET project)

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);

This request returns a structured JSON object:

{
  "error": "false",
  "reference": "project_reference",
  "info_title": "Paris fashion week 2024",
  "info_stage": "Confirmed",
  "info_stage_reference": "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_stage_reference String Technical name of 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_reference": "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_reference: "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);

This request returns a structured JSON object:

{
  "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_reference 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);

This request returns a structured JSON object:

{
  "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 clients

It returns a list of your clients. The clients are returned sorted by creation date, with the most recent clients appearing first. The list of clients 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/clients' \
--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 + "/clients", headers);

This request returns a structured JSON object:

{
  "error": "false",
  "next_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJtZW51X211bG11bCI6Im9wdDEiLCJudW1iZXIiOiIyMDAwMCIsInBhZ2UiOjEsInBlcnNvX2ludm9pY2UiOiJHRyIsInN0YWdlIjoicGFpZCIsIl9fdGltZSI6MTY5NzQ0NjEzNX0.jEs7aL3UzCNrjzwDtAUbq4Rt4T64nu2LBYC0NnQhHiA",
  "size": 338,
  "data_size": 50,
  "page": 1,
  "clients": [
    {
      "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"
      }
    },...
  ]
}

HTTP Endpoint

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

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.

Response

A JSON object containing the client information with properties like:

Property Type Description
next_token String A token will be returned if all clients have not been returned. Use it in another call to access the following clients
size Number The total number of clients available with these filters
data_size Number Number of clients returned on the current page
page Number The page number
clients Array An array of JSON objects, each representing a client. These objects are formatted according to a simplified version of the GET client response structure. (GET client)

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);

This request returns a structured JSON object:

{
  "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);

This request returns a structured JSON object:

{
  "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

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.

Suppliers

GET suppliers

It returns a list of your suppliers. The suppliers are returned sorted by creation date, with the most recent suppliers appearing first. The list of suppliers 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/suppliers' \
--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 + "/suppliers", headers);

This request returns a structured JSON object:

{
  "error": "false",
  "next_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJtZW51X211bG11bCI6Im9wdDEiLCJudW1iZXIiOiIyMDAwMCIsInBhZ2UiOjEsInBlcnNvX2ludm9pY2UiOiJHRyIsInN0YWdlIjoicGFpZCIsIl9fdGltZSI6MTY5NzQ0NjEzNX0.jEs7aL3UzCNrjzwDtAUbq4Rt4T64nu2LBYC0NnQhHiA",
  "size": 338,
  "data_size": 50,
  "page": 1,
  "suppliers": [
    {
      "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",
      "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"
      }
    },...
  ]
}

HTTP Endpoint

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

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.

Response

A JSON object containing the supplier information with properties like:

Property Type Description
next_token String A token will be returned if all suppliers have not been returned. Use it in another call to access the following suppliers
size Number The total number of suppliers available with these filters
data_size Number Number of suppliers returned on the current page
page Number The page number
suppliers Array An array of JSON objects, each representing a supplier. These objects are formatted according to a simplified version of the GET supplier response structure. (GET supplier)

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);

This request returns a structured JSON object:

{
  "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);

This request returns a structured JSON object:

{
  "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

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.

Products

GET products

It returns a list of your products. The products are returned sorted by creation date, with the most recent products appearing first. The list of products 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/products' \
--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 + "/products", headers);

This request returns a structured JSON object:

{
  "error": "false",
  "next_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJtZW51X211bG11bCI6Im9wdDEiLCJudW1iZXIiOiIyMDAwMCIsInBhZ2UiOjEsInBlcnNvX2ludm9pY2UiOiJHRyIsInN0YWdlIjoicGFpZCIsIl9fdGltZSI6MTY5NzQ0NjEzNX0.jEs7aL3UzCNrjzwDtAUbq4Rt4T64nu2LBYC0NnQhHiA",
  "size": 338,
  "data_size": 50,
  "page": 1,
  "products": [
    {
    "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",
    "supplier_reference": "supplier_reference",
    "package_reference": "package_reference",
    "commission": {
      "commission_mode": "purchase",
      "commission_regime": "percent",
      "value": "10"
      }
    },...
  ]
}

HTTP Endpoint

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

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.

Response

A JSON object containing the product information with properties like:

Property Type Description
next_token String A token will be returned if all products have not been returned. Use it in another call to access the following products
size Number The total number of products available with these filters
data_size Number Number of products returned on the current page
page Number The page number
products Array An array of JSON objects, each representing a product. These objects are formatted according to a simplified version of the GET product response structure. (GET product)

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);

This request returns a structured JSON object:

{
  "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);

This request returns a structured JSON object:

{
  "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

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.

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);

This request returns a structured JSON object:

{
  "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);

This request returns a structured JSON object:

{
  "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

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.

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);

This request returns a structured JSON object:

{
  "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_stage_reference": "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 invoices that are at a specific stage. The stage can be paid, completed or draft.
technical_name String You can filter invoices according to 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
next_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 on the current page
page Number The page number
invoices Array An array of JSON objects, each representing a invoice. These objects are formatted according to a simplified version of the GET invoice response structure. (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);

This request returns a structured JSON object:

{
  "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_stage_reference": "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_stage_reference, 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);

This request returns a structured JSON object:

{
  "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

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.

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
);

This request returns a structured JSON object:

{
  "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_stage_reference": "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_stage_reference, 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);

This request returns a structured JSON object:

{
  "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);

This request returns a structured JSON object:

{
  "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=projects.created' \
--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=projects.created", headers);

This request returns a structured JSON object:

{
  "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);

This request returns a structured JSON object:

{
  "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);

This request returns a structured JSON object:

{
  "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. Note: For multi-destination alternatives, only the primary destination is returned.
trip_subdestination String Subdestination of the alternative. Note: For multi-destination alternatives, only the primary subdestination is returned.
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