HIVEO API (1.3)

Download OpenAPI specification:Download

Introduction

The Hiveo API allows Hiveo customers to programmatically manage their own organisation and their suppliers.

Through the API you can, for example:

  • Retrieve dossier and document statuses from your suppliers,
  • Retrieve specific files from your suppliers,
  • Invite new suppliers,
  • Remind suppliers,
  • Invite new users to your organisation.

The Hiveo API is organised around REST and JSON, and uses standard HTTP response codes, verbs and authentication.

Release notes

1.3

  • /api/invite-depositor : On success, now returns the current invitations linked to this relation
  • /api/collectors/{internal-id}/relations: Remove filterDate and fromLastModifiedDate attributes, which we’re not working properly
  • Added 2 endpoints to activate and deactivate relations:
    • POST /api/collectors/{internal-id}/activate-relation
    • POST/api/collectors/{internal-id}/close-relation
  • Added withInactiveRelation filter in GET /api/collectors/{internal-id}/relations
  • Added legalNotice property to the Organisation object.

1.0

First version of our collector API.

Overview

Environments

We provide 2 different environments:

  1. Our Test environment, used for testing our API. It is accessible on weekdays between 7:30 a.m. and 8:30 p.m. (CET).
  2. Our Production environment, used for… production :)

When creating your account, we will provide credentials for both environments.

Test environment

This environment is a replica from our production environment: You’ll be able to Test on near-real data. If you already have a user account on our production environnement, you’ll be able to use it to connect to our Test environnement as well.

However, it is “read-only”: Actions are not really generated. For example, when you invite a new supplier, the following actions are performed in our production environnement:

  1. The relation between you and the supplier organisation is created ;
  2. Hiveo sends invitation emails to the contacts you specified for this supplier organisation ;
  3. The contacts create their account on Hiveo and are attached to the relation ;
  4. They upload the documents ;
  5. You can retrieve these information and documents from this relation.

On our Test environment:

  1. The relation between you and the supplier organisation is created ;
  2. Hiveo DOES NOT SEND invitation emails to the contacts you specified for this supplier organisation ;
  3. The contacts will remain as guests ;
  4. The relation will remain with no active contact and no documents ;
  5. You will be able to retrieve these information.

The data contained on our Test environment will be updated periodically, at our discretion.

Differences between our environnments

The table below lists some possible actions and their results in each environment:

Action Test environment Production environment
Invite a user to your own organisation no email sent
Invite a new supplier no email sent
Get all information from your suppliers
Get information for a specific supplier
Close a specific relation no email sent
Reopen a previously closed relation no email sent
Get information for a specific document
Get a specific PDF file
Get all current documents and dossiers for a specific supplier
Send reminders to all non-conform suppliers no email sent
Get a supplier’s reminder history

API versioning

The Hiveo API is accessed through an generic URL. If you want to call a specific version of the Hiveo API, use the x-version HTTP header to specify it. For example:

x-version:1.2

Any breaking changes to the API will be introduced through a new version number.

Non-breaking changes may be introduced without changing version. These may include additional fields to JSON data structures, optional parameters to API calls, new features that can be exposed through existing API calls, or new API calls.

Our API versioning uses 2 digits, such as major.minor (1.0, 1.1…). An increment in the major digit means that ground-breaking changes have been introduced (ex: rework on entire resources, major changes in the authentication system…).

Security

All endpoints require authentication. We use the following Oauth2 grant types:

Operation type Oauth2 grant types Label
Actions not related to a specific user (mostly read-only) Client Credentials Grant OauthClientSecurity
Actions done by a specific user (such as invitations) Password Grant or Authorization Code Grant OauthUserSecurity

To authenticate API requests, you must provide a valid bearer token in an HTTP header:

Authorization: Bearer {bearer_token}

Here is an example authentication request for the Client Credentials Grant type:

POST /auth/realms/hiveo/protocol/openid-connect/token HTTP/1.1
Host: https://authdev.hiveo.fr
Content-Type: application/x-www-form-urlencoded
Authorization: Basic c3ViY2xpYzpjZDg5ZjM1OC1iMjhiLTRiMjktYjBhZC0wNWEzYjcxMWFjZDc=
Content-Type: application/x-www-form-urlencoded

client_secret=<your client secret>&client_id=<your client id>&grant_type=client_credentials&scope=openid

Pagination

Many of our API resources use pagination. You can select whatever you want to receive using page and size parameters.

⚠️ Most of our endpoints limit the number of returned results to 100, even if you pass a superior size.

Errors

Hiveo uses conventional HTTP response codes to indicate the success or failure of an API request.

In general:

  • 2xx codes indicate success,
  • 4xx codes indicate an error that failed given the information provided (e.g., a required parameter was omitted, the resource does not exist…),
  • 5xx codes indicate an error with Hiveo’s servers.
HTTP code Label Meaning
200 OK Success
201 Created A resource has been created
202 Accepted The request has been accepted for processing, but the processing has not been completed
400 Bad Request The request was unacceptable, often due to missing a required parameter
401 Unauthorized No valid API key provided
402 Request Failed The parameters were valid but the request failed
403 Forbidden The API key doesn’t have permissions to perform the request
404 Not Found The requested resource doesn’t exist
409 Conflict The request conflicts with another request
429 Too Many Requests Too many requests hit the API too quickly
500, 502, 503, 504 Server Errors Something went wrong on Hiveo’s side

Getting started

The Hiveo API uses several notions and objects. We will describe them here.

Organisations, collectors, depositors and relations

Companies and their work sites are call organisations. Each organisation has a corresponding national identifier, called national ID, and a reference country code.

For example:

  1. The french organisation Hiveo (top level) has the national ID 841226053 (SIREN).
  2. The french Hiveo headquarter (our only work site) has the national ID 84122605300012 (SIRET).
  3. Both have the FR country code.

On Hiveo, collector organisations (our customers) invite their suppliers as depositors. Thus they create relations between them.

Each organisation is referenced with an Hiveo ID (also called internal ID), built by concatening the country code and the national ID of the organisation (ex: Hiveo top level organisation has the Hiveo ID FR-841226053):

    "country": "FR"
    "nationalId": "841226053"
    "internalId": "FR-841226053"

To sum up:

  1. Organisations can be collector, depositor, or both.
  2. You are a collector, your suppliers are depositors.
  3. A collector has relations with its depositors.

Invitations and relations

Whenever you successfully invite a depositor on Hiveo, whereas by API or by our web application, the relation is created and active. This is an important point to understand: The relation is created and active, whether the depositor has registered or not.

So among your active relations, you can distinguish:

  1. Relations with depositors that registered to Hiveo,
  2. Relations with depositors that haven’t yet registered to Hiveo. These invitations are sent again when you use the reminders functionnality, by API or by our web application.

💡 Note that you cannot invite a depositor that is no longer running and has been legally declared closed.

Dossiers and documents

Each depositor uploads documents on Hiveo. A Hiveo document has:

  • A type (ex: Justificatif d’Immatriculation Kbis (Extrait RCS) ) which is very specific to the nature of the document,
  • Belongs to an usage (ex: Justificatif d’Immatriculation),
  • And is sorted in a dossier.

Every depositor has a legal dossier, containing documents from the following usages:

  1. Justificatif d’Immatriculation
  2. Attestation sociale de vigilance
  3. Liste des salariés étrangers soumis à autorisation de travail

If you collect more than these 3 usages, your depositors will also have a complementary dossier, containing the rest of the collected documents.

Versions of documents are called revisions. A same PDF file can be linked to several revisions, corresponding to either:

  • Different attempts to upload and validate the PDF file
  • Revisions of several document types (for example, in France, a same PDF file can be both of type Attestation Décennale Standard and of type Attestation de Responsibilité Professionnelle)

A revision has several attributes related to its validity state:

  • usable if the depositor has gone through the whole upload process (non usable revisions are drafts that never reach the depositor’s dossiers)
  • valid if the document has passed all validation rules: it has a start validity date, and an end validity date, but the revision will always be considered valid between these 2 dates
  • operational if the document is valid at the specified date – This notion is relative

Users and contacts

Users can be attached to one of several companies (e.g top-level organisations). Once a user is invited to join a company, she can subscribe to every work site (e.g child organisations) she needs to.

When subscribing to a child organisation, a user:

  1. Exposes herself on this organisation: Users from organisations in relation will see her as a contact of this organisation,
  2. Will receive notifications for this organisation,
  3. Is able to select this child organisation on her menu.

With the Hiveo API you can:

  1. Invite new users on your own organisation,
  2. Invite a new contact on one of your relations.

Reminders

Hiveo provide collectors with the ability to send manual reminders to their suppliers. These reminders are of several types:

  1. Invitation reminders, used for users and contacts,
  2. Documents reminders, used to warn non up to date suppliers.

Reminders are only sent when needed: A supplier with valid dossiers and contacts will NOT be notified.

Invitation reminders are only manual: They can be sent by users, or programmatically. Documents reminders are automatically sent by Hiveo, and can also be sent manually or programmatically by users.

Use cases

Example 1: Retrieve your relations directory

To get all your suppliers at once, use:

GET /api/collectors/{internal-id}/relations

This will return all your active relations, and all their related data (contact information, dossier states, document states…).

This endpoint supports several filters, please refer to the API OpenAPI description for details.

That is the main endpoint to use to get information from Hiveo.

💡 Note that by default, Hiveo returns only your active relations. If you need to also get your deactivated relations, use the withInactiveRelation filter.

Example 2: Get data from a document

To access data from a document (for example, workforce and payroll values listed in a French URSSAF document), use:

GET /api/revisions/{revision}

The response contains a revision object, which includes all metadata from the document a key/value pairs in its data attribute:

{
  "revision": {
    "data": {
      "valid_verification_proof": "true",
      "valid_from_date": "31/07/2019",
      "valid_to_date": "31/01/2020",
      "issue_date": "11/09/2019",
      "workforce": "4",
      "payroll": "17000",
      "reference_date": "31/07/2019",
      "page_count": "2"
    }
  }
}

Example 4: Check if an organisation which you are in relation with is active or closed

Hiveo lets you know if your relations work sites and companies are actually active or closed.

For example, you can retrieve this information in your relations attributes:

GET /api/collectors/{internal-id}/relations

The response contains a depositor object corresponding to your relation organisation, which includes these information in the status attribute:

{
  "depositor": {
    "status": "ACTIVE",
    "closed": false
  }
}

The status attribute can take several values:

  1. ACTIVE: The organisation is legally registered and running,
  2. INSOLVANCY: The organisation is under a legal procedure, and might enter bankruptcy, but not necessarily,
  3. CLOSED: The organisation is no longer running and has been legally declared closed.

💡 Note that you can also use the closed boolean attribute, that is generated from the status value.

When a company is legally declared closed, Hiveo automatically deactivates all relations involving this company.

Example 5: Check if a relation has subscribed to Hiveo, or not

Hiveo lets you know if your relations have already subscribed to Hiveo or not.

For example, you can retrieve this information in your relations attributes:

GET /api/collectors/{internal-id}/relations

The response contains a depositor object corresponding to your relation organisation, which includes contacts information in its additionalInformation attribute:

{
  "depositor": {
    "additionalInformation": {
      "contacts": {
        "nbTotal": 1,
        "nbActive": 0,
        "withActive": false,
        "nbAdminProfile": 1,
        "nbMemberProfile": 1,
        "withAdmin": true
      }
    }
  }
}

The withActive attribute lets you know if at least one active contact is available for this relation. If not, this depositor has not registered yet.

Example 6: Close an existing relation

To close an existing relation, use:

POST /organisation/api/collectors/{internal-id}/close-relation

Body contains:

{
  "collector": "<Your internal ID>",
  "depositor": "<The Depositor internal ID>"
}

⚠️ When closing a relation, all custom information (categories, usual name…) will be lost.

Example 7: Check if a supplier has an OFA account

Hiveo is connected to Once For All / Attestation Légale and automatically retrieves available documents on OFA.

For example, you can retrieve this information in your relations attributes:

GET /api/collectors/{internal-id}/relations

The response contains a depositor object corresponding to your relation organisation, which includes providers information.

For example, at the organisation level:

{
  "depositor": {
  "internalId": "FR-52773773800023",
  "country": "FR",
  "nationalId": "52773773800023",
  "name": "OFA",
  "documentProviders": [
    "ALG"
  ],
}

Also at the document level in the same response:

{
  "documents": [
    {
      "label": "Justificatif d'immatriculation Kbis (Extrait RCS)",
      "providedBy": "ALG"
    }
  ]
}

Other examples

Type Name Needed rights Authentication theme Resource
Invitations Invite a user to your own organisation Write User POST /api/organisations/{internal-id}/contacts
Invitations Invite a new supplier Write User POST /api/invite-depositor
Relations Get all information from your suppliers Read Machine GET /api/collectors/{internal-id}/relations
Relations Get information for a specific supplier Read Machine GET accept: application/json /api/collectors/{internal-id}/relations?depositor={depositor-internal-id}
Relations Close a specific relation Write User POST /organisation/api/collectors/{internal-id}/close-relation
Relations Reopen a previously closed relation Write User POST /organisation/api/collectors/{internal-id}/activate-relation
Documents Get information for a specific document Read User GET /api/revisions/{revision}
Documents Get a specific PDF file Read User GET accept: application/pdf /api/revisions/{revision}/file
Documents Get all current documents and dossiers for a specific supplier Read Machine GET accept: application/zip /api/collectors/{internal-id}/relations?depositor={depositor-internal-id}
Reminders Send reminders to all non-conform suppliers Write User POST /api/collectors/{internal-id}/manual-reminds
Reminders Get a supplier’s reminder history Read Machine GET ​/api​/collectors​/{internal-id}​/reminds

Reference

Available Hiveo document types

key value Usage Dossier
fr_kbis_rcs Justificatif d’immatriculation Kbis (Extrait RCS) Justificatif d’immatriculation Documents légaux
fr_kbis_ti Justificatif d’immatriculation Kbis (TI) Justificatif d’immatriculation Documents légaux
fr_extrait_d1 Justificatif d’immatriculation D1 (Extrait RM) Justificatif d’immatriculation Documents légaux
fr_extrait_sirene Justificatif d’immatriculation Extrait répertoire SIRENE Justificatif d’immatriculation Documents légaux
fr_attestation_urssaf Attestation sociale de vigilance URSSAF Attestation sociale de vigilance Documents légaux
fr_attestation_msa Attestation sociale de vigilance MSA Attestation sociale de vigilance Documents légaux
fr_attestation_rsi Attestation sociale de vigilance RSI Attestation sociale de vigilance Documents légaux
fr_exemption_attestation_vigilance Attestation sociale de vigilance - Attestation sur l’honneur Attestation sociale de vigilance Documents légaux
fr_liste_salaries_etrangers_soumis_a_autorisation_de_travail Liste des salariés étrangers soumis à autorisation de travail Liste des salariés étrangers soumis à autorisation de travail Documents légaux
fr_assurance_responsabilite_civile_professionnelle Assurance responsabilité civile professionnelle Assurance Documents complémentaires
fr_assurance_decennale_standard Attestation décennale standard Assurance Documents complémentaires
fr_attestation_fiscale_societe_independante Attestation fiscale - Société indépendante Attestation fiscale Documents complémentaires
fr_attestation_fiscale_societe_fille Attestation fiscale - Société fille Attestation fiscale Documents complémentaires
fr_attestation_fiscale_societe_mere Attestation fiscale - Société mère Attestation fiscale Documents complémentaires
fr_attestation_fiscale_cerfa_3666_1 CERFA 3666-SD Feuillet 1 (IS) Attestation fiscale Documents complémentaires
fr_attestation_fiscale_cerfa_3666_2 CERFA 3666-SD Feuillet 2 (IR) Attestation fiscale Documents complémentaires
fr_attestation_fiscale_bordereau_situation Bordereau de situation Attestation fiscale Documents complémentaires
fr_attestation_fiscale_p237 Attestation fiscale valant P237 Attestation fiscale Documents complémentaires
fr_attestation_fiscale_avis_situation Avis de situation déclarative à l’impôt sur le revenu Attestation fiscale Documents complémentaires
fr_exemption_attestation_fiscale Attestation fiscale - Attestation sur l’honneur Attestation fiscale Documents complémentaires
fr_attestation_caisse_conges_payes Attestation caisse de congés payés Attestation caisse de congés payés Documents complémentaires
fr_attestation_garantie_financiere Attestation de Garantie Financière Attestation de Garantie Financière Documents complémentaires
fr_exemption_garantie_financiere Garantie financière - Attestation sur l’honneur Attestation de Garantie Financière Documents complémentaires
fr_licence_transport_marchandises_interieur Licence de transport intérieur pour marchandises Licence de transport Documents complémentaires
fr_licence_transport_marchandises_communautaire Licence de transport communautaire pour marchandises Licence de transport Documents complémentaires
fr_licence_transport_marchandises_international Licence de transport International de marchandises Licence de transport Documents complémentaires
fr_licence_transport_personnes_communautaire Licence de transport communautaire pour personnes Licence de transport Documents complémentaires
fr_exemption_licence_transport Licence de transport - Attestation sur l’honneur Licence de transport Documents complémentaires
fr_charte_rse Charte RSE RSE Documents complémentaires
fr_attestation_capacite Attestation de capacité Qualification Documents complémentaires
fr_qualification_attestation_formation Attestation de formation Qualification Documents complémentaires
fr_qualification_caces Certificat d’Aptitude à la Conduite En Sécurité (CACES) Qualification Documents complémentaires
fr_qualification_ilo_osh_2001 Certificat ILO-OSH 2001 Qualification Documents complémentaires
fr_qualification_iso_13485 Certificat ISO 13485 Qualification Documents complémentaires
fr_qualification_iso_14001 Certificat ISO 14001 Qualification Documents complémentaires
fr_qualification_iso_18001 Certificat ISO 18001 Qualification Documents complémentaires
fr_qualification_iso_3834_2 Certificat ISO 3834-2 Qualification Documents complémentaires
fr_qualification_iso_50001 Certificat ISO 50001 Qualification Documents complémentaires
fr_qualification_iso_9001 Certificat ISO 9001 Qualification Documents complémentaires
fr_qualification_mase_uic Certificat MASE-UIC Qualification Documents complémentaires
fr_qualification_ohsas_18001 Certificat OHSAS 18001 Qualification Documents complémentaires
fr_qualification_qualibat Certificat Qualibat Qualification Documents complémentaires
fr_qualification_qualifelec Certificat Qualifelec Qualification Documents complémentaires
fr_qualification_qualipac Certificat QualiPAC Qualification Documents complémentaires
fr_qualification_qualipv_bat Certificat QualiPV Bat Qualification Documents complémentaires
fr_qualification_qualipv_elec Certificat QualiPV Elec Qualification Documents complémentaires
fr_qualification_rge_chauffage Certificat RGE Chauffage + Qualification Documents complémentaires
fr_qualification_ecolabel_cecor Ecolabel CECOR Qualification Documents complémentaires
fr_qualification_fds Fiche de Données Sécurité (FDS) Qualification Documents complémentaires
fr_titre_habilitation Titre d’habilitation Qualification Documents complémentaires
fr_aae_metaux_precieux Autorisation administrative d’exercer Commerce des métaux précieux Autorisation administrative d’exercer Documents complémentaires
fr_aae_inscription_barreau Autorisation administrative d’exercer Inscription au Barreau Autorisation administrative d’exercer Documents complémentaires
fr_aae_inscription_registre_transports Autorisation administrative d’exercer Inscription registre des transports Marchandises Autorisation administrative d’exercer Documents complémentaires
fr_aae_portage_salarial Autorisation administrative d’exercer Activité de portage salarial Autorisation administrative d’exercer Documents complémentaires
fr_aae_installations_classees Autorisation administrative d’exercer Installations classées Autorisation administrative d’exercer Documents complémentaires
fr_aae_inscription_ordre_architectes Autorisation administrative d’exercer Inscription Ordre des Architectes Autorisation administrative d’exercer Documents complémentaires
fr_aae_activite_privee_securite Autorisation administrative d’exercer Activité privée de sécurité Autorisation administrative d’exercer Documents complémentaires
fr_aae_activite_travail_temporaire Autorisation administrative d’exercer Activité d’entreprise de travail temporaire Autorisation administrative d’exercer Documents complémentaires
fr_aae_habilitation_funeraire Autorisation administrative d’exercer Habilitation funéraire Autorisation administrative d’exercer Documents complémentaires
fr_aae_activite_collecte_transport_dechets Autorisation administrative d’exercer Activité de collecte et transport de déchets Autorisation administrative d’exercer Documents complémentaires
fr_aae_installation_mobile_decontamination_dechets_PCB Autorisation administrative d’exercer Installation mobile de décontamination des déchets contenant des PCB Autorisation administrative d’exercer Documents complémentaires
fr_aae_transporteur_aerien Autorisation administrative d’exercer Transporteur aérien Autorisation administrative d’exercer Documents complémentaires
fr_aae_inscription_ordre_geometres_experts Autorisation administrative d’exercer Inscription à l’Ordre des Géomètres-Experts Autorisation administrative d’exercer Documents complémentaires
fr_aae_agrement_entreprise_solidaire_utilite_sociale Autorisation administrative d’exercer Agrément d’une entreprise solidaire d’utilité sociale Autorisation administrative d’exercer Documents complémentaires
fr_aae_activite_negoce_courtage_dechets Autorisation administrative d’exercer Activité de négoce et courtage de déchets Autorisation administrative d’exercer Documents complémentaires
fr_aae_inscription_registre_transports_voyageurs Autorisation administrative d’exercer Inscription registre des transports Voyageurs Autorisation administrative d’exercer Documents complémentaires
fr_aae_inscription_registre_transports_commissionnaires Autorisation administrative d’exercer Inscription registre des transports Commissionnaires Autorisation administrative d’exercer Documents complémentaires
fr_aae_agence_mannequins Autorisation administrative d’exercer Agence de Mannequins Autorisation administrative d’exercer Documents complémentaires
fr_exemption_aae Autorisation administrative d’exercer - Attestation sur l’honneur Autorisation administrative d’exercer Documents complémentaires
fr_attestation_mutuelle Attestation Mutuelle Attestation Mutuelle Prévoyance Retraite Documents complémentaires
fr_attestation_retraite Attestation Retraite Attestation Mutuelle Prévoyance Retraite Documents complémentaires
fr_attestation_prevoyance Attestation Prévoyance Attestation Mutuelle Prévoyance Retraite Documents complémentaires
fr_declaration_emploi_travailleurs_handicapes Déclaration d’emploi des travailleurs handicapés Déclaration d’emploi des travailleurs handicapés Documents complémentaires
fr_declaration_activite_prestataire_formation Déclaration d’activité de prestataire de formation - Récépissé Déclaration d’activité de prestataire de formation Documents complémentaires
fr_licence_entrepreneur_spectacle Licence des entrepreneurs du spectacle Licence des entrepreneurs du spectacle Documents complémentaires

Authentication

OauthUserSecurity

Security Scheme Type OAuth2
password OAuth Flow
Token URL: https://authdev.hiveo.fr/auth/realms/hiveo/protocol/openid-connect/token
Scopes:
  • offline_access -

    offline_access

OauthClientSecurity

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: https://authdev.hiveo.fr/auth/realms/hiveo/protocol/openid-connect/token
Scopes:
  • offline_access -

    offline_access

Contacts

Contacts of an organisation are users who have linked to this organisation, and thus can manage it.

Get the contacts of an organisation

Get the contacts of a specific organisation, using its Hiveo internal ID.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the organisation

query Parameters
direct
boolean
Default: false

If true, only get the direct contacts. If false, also get the parent's contacts

query
string

Term to search in the contacts list. Search works on username, email, firstName, lastName, phone, jobs

page
integer <int32>

Pagination - Page number of the requested page

size
integer <int32>

Pagination - Number of elements on each page

sort
Array of strings

Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported

Responses

200

OK

401

Unauthorized

403

Forbidden

404

The organisation cannot be found

get/api/organisations/{internal-id}/contacts

Development server

https://apidev.hiveo.fr/api/organisations/{internal-id}/contacts

Test server

https://apistaging.hiveo.fr/api/organisations/{internal-id}/contacts

Production server

https://api.hiveo.fr/api/organisations/{internal-id}/contacts

Relations

Close or activate previous relations.

Get existing relations for a collector organisation

Get all your relations at once. With this resource you can:

  • Get all your relations, or a subset of them
  • Get your relations dossiers and documents statuses

Use:

  • application/zip to export relation files (*.zip)
  • application/pdf to get your relations' conformity certificates (*.pdf)
Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the collector organisation

query Parameters
filterDossiers
string

Id of the dossiers to search for not operational relations. If not setted, will search on all selected dossiers for the relation

onlyNoRegisteredContact
string

Only get relations without active contacts

onlyHasExempted
string

Only get relations with at least one operational exempted revision

onlyOperational
string

Only get operational relations on requested dossiers

onlyNotOperational
string

Only get not operational relations on requested dossiers

categories
string

Only get relations with the specified categories

depositors
string

Only get relations corresponding to these Hiveo internal ID (-)

providers
string

Only get relations with at least one document from this external provider

query
string

Terms to search in the relation

withInactiveRelation
string

Also get inactive relations

page
integer <int32>

Pagination - Page number of the requested page

size
integer <int32>

Pagination - Number of elements on each page

sort
Array of strings

Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

header Parameters
Accept-Language
string

User locale (ex: fr-FR)

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get/api/collectors/{internal-id}/relations

Development server

https://apidev.hiveo.fr/api/collectors/{internal-id}/relations

Test server

https://apistaging.hiveo.fr/api/collectors/{internal-id}/relations

Production server

https://api.hiveo.fr/api/collectors/{internal-id}/relations

Response samples

Content type
Copy
Expand all Collapse all
{
  • "content":
    [
    ],
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "sort": { },
  • "totalElements": 0,
  • "totalPages": 0
}

Creates or re-activates a relation from the collector initiative

Activate a previously deactivated relation with a supplier, using its Hiveo internal ID.

Authorizations:
path Parameters
internal-id
required
string

Internal ID of the collector

Request Body schema: application/json

relation

collector
required
string

Hiveo internal ID (-) of the collector organisation for this relation

depositor
required
string

Hiveo internal ID (-) of the depositor organisation for this relation

Responses

200

OK

201

Created

400

The relation is already currently active

401

Unauthorized

403

Forbidden

404

The relation cannot be found

post/api/collectors/{internal-id}/activate-relation

Development server

https://apidev.hiveo.fr/api/collectors/{internal-id}/activate-relation

Test server

https://apistaging.hiveo.fr/api/collectors/{internal-id}/activate-relation

Production server

https://api.hiveo.fr/api/collectors/{internal-id}/activate-relation

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "collector": "string",
  • "depositor": "string"
}

Closes a relation from the collector initiative

Close an active relation with a supplier, using its Hiveo internal ID.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the collector organisation

Request Body schema: application/json

A relation between 2 organisations

collector
required
string

Hiveo internal ID (-) of the collector organisation for this relation

depositor
required
string

Hiveo internal ID (-) of the depositor organisation for this relation

Responses

200

OK

201

Created

400

The relation is not currently active

401

Unauthorized

403

Forbidden

404

The relation cannot be found

post/api/collectors/{internal-id}/close-relation

Development server

https://apidev.hiveo.fr/api/collectors/{internal-id}/close-relation

Test server

https://apistaging.hiveo.fr/api/collectors/{internal-id}/close-relation

Production server

https://api.hiveo.fr/api/collectors/{internal-id}/close-relation

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "collector": "string",
  • "depositor": "string"
}

Invitations

Invite new depositor organisations, or new contacts to your organisation.

Invite a depositor organisation

Invite a depositor organisation to join your network.

When successful, this will create a new relation between the selected inviting organisation (must be one of your scope, such as one of your work site) and the invited depositor organisation.

Authorizations:
Request Body schema: application/json

An invitation request, composed of:

  • An inviting organisation Hiveo internal ID
  • An invited organisation Hiveo internal ID
  • An optional internal code (user data)
  • Optional categories (user data)
  • Optional contacts to invite on this organisation
categories
Array of strings
guests
Array of objects (Guest)
internalCode
string
invitedOrganisationInternalId
string
invitingOrganisationInternalId
string

Responses

200

OK

201

Created

401

Unauthorized

403

Forbidden

404

One of the specified organisations (inviter or invitee) cannot be found

post/api/invite-depositor

Development server

https://apidev.hiveo.fr/api/invite-depositor

Test server

https://apistaging.hiveo.fr/api/invite-depositor

Production server

https://api.hiveo.fr/api/invite-depositor

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "categories":
    [
    ],
  • "guests":
    [
    ],
  • "internalCode": "string",
  • "invitedOrganisationInternalId": "string",
  • "invitingOrganisationInternalId": "string"
}

Add contacts to an organisation

Invite new contacts to one of the collector's organisations. This resource is used to invite new internal contacts of your company.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the organisation

Request Body schema: application/json

Contacts to invite on this organisation

guests
required
Array of objects (Guest)

Users to add to the organisation

Responses

200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/api/organisations/{internal-id}/contacts

Development server

https://apidev.hiveo.fr/api/organisations/{internal-id}/contacts

Test server

https://apistaging.hiveo.fr/api/organisations/{internal-id}/contacts

Production server

https://api.hiveo.fr/api/organisations/{internal-id}/contacts

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "guests":
    [
    ]
}

Reminds

Remind your relations to update their data, or access to an organisation remind history.

Send reminders to relations

Send reminders to the specified relations.

Only relations with non operational documents, or with pending contact invitations will receive reminder notifications.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the collector organisation that requests the reminds

Request Body schema: application/json

query

actualDossiersToFilter
Array of integers <int64>
categories
Array of strings
collectors
Array of strings
depositors
Array of strings
filterDossiers
Array of integers <int64>
onlyHasExempted
boolean
onlyNoRegisteredContact
boolean
onlyNotOperational
boolean
onlyOperational
boolean
providers
Array of strings
query
string

Responses

200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/api/collectors/{internal-id}/manual-reminds

Development server

https://apidev.hiveo.fr/api/collectors/{internal-id}/manual-reminds

Test server

https://apistaging.hiveo.fr/api/collectors/{internal-id}/manual-reminds

Production server

https://api.hiveo.fr/api/collectors/{internal-id}/manual-reminds

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "actualDossiersToFilter":
    [
    ],
  • "categories":
    [
    ],
  • "collectors":
    [
    ],
  • "depositors":
    [
    ],
  • "filterDossiers":
    [
    ],
  • "onlyHasExempted": true,
  • "onlyNoRegisteredContact": true,
  • "onlyNotOperational": true,
  • "onlyOperational": true,
  • "providers":
    [
    ],
  • "query": "string"
}

Get reminder history

Get the reminders history of a specific organisation.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the collector organisation

query Parameters
depositor
string

Hiveo internal ID (-) of the depositor organisation whose reminds history is requested

page
integer <int32>
Default: 0

Pagination - Page number of the requested page

size
integer <int32>
Default: 10

Pagination - Number of elements on each page

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get/api/collectors/{internal-id}/reminds

Development server

https://apidev.hiveo.fr/api/collectors/{internal-id}/reminds

Test server

https://apistaging.hiveo.fr/api/collectors/{internal-id}/reminds

Production server

https://api.hiveo.fr/api/collectors/{internal-id}/reminds

Organisations

Access to an organisation details, both company or work site details.

Get an organisation details

Get a specific organisation using its Hiveo internal ID.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the organisation

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get/api/organisations/{internal-id}

Development server

https://apidev.hiveo.fr/api/organisations/{internal-id}

Test server

https://apistaging.hiveo.fr/api/organisations/{internal-id}

Production server

https://api.hiveo.fr/api/organisations/{internal-id}

Get an organisation direct children details

Get the direct children of a specific organisation using its Hiveo internal ID.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the organisation

query Parameters
page
integer <int32>
Default: 0

Pagination - Page number of the requested page

size
integer <int32>
Default: 5

Pagination - Number of elements on each page

Responses

200

OK

401

Unauthorized

403

Forbidden

404

If the organisation can't be found

get/api/organisations/{internal-id}/children

Development server

https://apidev.hiveo.fr/api/organisations/{internal-id}/children

Test server

https://apistaging.hiveo.fr/api/organisations/{internal-id}/children

Production server

https://api.hiveo.fr/api/organisations/{internal-id}/children

Documents

Access revisions of a specific document type, and related PDF documents and verification proofs.

Get a document revision

Get a document revision. A document revision contains all metadata relative to this document.

A revision is:

  • usable if the depositor has gone through the whole upload process
  • valid if the document has passed all validation rules
  • operational if the document is valid at the specified date
Authorizations:
path Parameters
revision
required
string

Identifier of the revision

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get/api/revisions/{revision}

Development server

https://apidev.hiveo.fr/api/revisions/{revision}

Test server

https://apistaging.hiveo.fr/api/revisions/{revision}

Production server

https://api.hiveo.fr/api/revisions/{revision}

Download revision file

Get the PDF file corresponding to this specific revision.

Authorizations:
path Parameters
revision
required
string

Identifier of the revision

header Parameters
Accept-Language
string

User locale (ex: fr-FR)

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get/api/revisions/{revision}/file

Development server

https://apidev.hiveo.fr/api/revisions/{revision}/file

Test server

https://apistaging.hiveo.fr/api/revisions/{revision}/file

Production server

https://api.hiveo.fr/api/revisions/{revision}/file

Download proof file

If it exists, get the proof file corresponding to this specific revision.

Authorizations:
path Parameters
revision
required
string

Identifier of the revision

header Parameters
Accept-Language
string

User locale (ex: fr-FR)

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get/api/revisions/{revision}/proof

Development server

https://apidev.hiveo.fr/api/revisions/{revision}/proof

Test server

https://apistaging.hiveo.fr/api/revisions/{revision}/proof

Production server

https://api.hiveo.fr/api/revisions/{revision}/proof

Endpoints added in version 1.3

This section lists all endpoints added in version 1.3.

Creates or re-activates a relation from the collector initiative

Activate a previously deactivated relation with a supplier, using its Hiveo internal ID.

Authorizations:
path Parameters
internal-id
required
string

Internal ID of the collector

Request Body schema: application/json

relation

collector
required
string

Hiveo internal ID (-) of the collector organisation for this relation

depositor
required
string

Hiveo internal ID (-) of the depositor organisation for this relation

Responses

200

OK

201

Created

400

The relation is already currently active

401

Unauthorized

403

Forbidden

404

The relation cannot be found

post/api/collectors/{internal-id}/activate-relation

Development server

https://apidev.hiveo.fr/api/collectors/{internal-id}/activate-relation

Test server

https://apistaging.hiveo.fr/api/collectors/{internal-id}/activate-relation

Production server

https://api.hiveo.fr/api/collectors/{internal-id}/activate-relation

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "collector": "string",
  • "depositor": "string"
}

Closes a relation from the collector initiative

Close an active relation with a supplier, using its Hiveo internal ID.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the collector organisation

Request Body schema: application/json

A relation between 2 organisations

collector
required
string

Hiveo internal ID (-) of the collector organisation for this relation

depositor
required
string

Hiveo internal ID (-) of the depositor organisation for this relation

Responses

200

OK

201

Created

400

The relation is not currently active

401

Unauthorized

403

Forbidden

404

The relation cannot be found

post/api/collectors/{internal-id}/close-relation

Development server

https://apidev.hiveo.fr/api/collectors/{internal-id}/close-relation

Test server

https://apistaging.hiveo.fr/api/collectors/{internal-id}/close-relation

Production server

https://api.hiveo.fr/api/collectors/{internal-id}/close-relation

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "collector": "string",
  • "depositor": "string"
}

Endpoints added in version 1.0

This section lists all endpoints added in version 1.0.

Invite a depositor organisation

Invite a depositor organisation to join your network.

When successful, this will create a new relation between the selected inviting organisation (must be one of your scope, such as one of your work site) and the invited depositor organisation.

Authorizations:
Request Body schema: application/json

An invitation request, composed of:

  • An inviting organisation Hiveo internal ID
  • An invited organisation Hiveo internal ID
  • An optional internal code (user data)
  • Optional categories (user data)
  • Optional contacts to invite on this organisation
categories
Array of strings
guests
Array of objects (Guest)
internalCode
string
invitedOrganisationInternalId
string
invitingOrganisationInternalId
string

Responses

200

OK

201

Created

401

Unauthorized

403

Forbidden

404

One of the specified organisations (inviter or invitee) cannot be found

post/api/invite-depositor

Development server

https://apidev.hiveo.fr/api/invite-depositor

Test server

https://apistaging.hiveo.fr/api/invite-depositor

Production server

https://api.hiveo.fr/api/invite-depositor

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "categories":
    [
    ],
  • "guests":
    [
    ],
  • "internalCode": "string",
  • "invitedOrganisationInternalId": "string",
  • "invitingOrganisationInternalId": "string"
}

Get an organisation details

Get a specific organisation using its Hiveo internal ID.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the organisation

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get/api/organisations/{internal-id}

Development server

https://apidev.hiveo.fr/api/organisations/{internal-id}

Test server

https://apistaging.hiveo.fr/api/organisations/{internal-id}

Production server

https://api.hiveo.fr/api/organisations/{internal-id}

Get an organisation direct children details

Get the direct children of a specific organisation using its Hiveo internal ID.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the organisation

query Parameters
page
integer <int32>
Default: 0

Pagination - Page number of the requested page

size
integer <int32>
Default: 5

Pagination - Number of elements on each page

Responses

200

OK

401

Unauthorized

403

Forbidden

404

If the organisation can't be found

get/api/organisations/{internal-id}/children

Development server

https://apidev.hiveo.fr/api/organisations/{internal-id}/children

Test server

https://apistaging.hiveo.fr/api/organisations/{internal-id}/children

Production server

https://api.hiveo.fr/api/organisations/{internal-id}/children

Add contacts to an organisation

Invite new contacts to one of the collector's organisations. This resource is used to invite new internal contacts of your company.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the organisation

Request Body schema: application/json

Contacts to invite on this organisation

guests
required
Array of objects (Guest)

Users to add to the organisation

Responses

200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/api/organisations/{internal-id}/contacts

Development server

https://apidev.hiveo.fr/api/organisations/{internal-id}/contacts

Test server

https://apistaging.hiveo.fr/api/organisations/{internal-id}/contacts

Production server

https://api.hiveo.fr/api/organisations/{internal-id}/contacts

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "guests":
    [
    ]
}

Get the contacts of an organisation

Get the contacts of a specific organisation, using its Hiveo internal ID.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the organisation

query Parameters
direct
boolean
Default: false

If true, only get the direct contacts. If false, also get the parent's contacts

query
string

Term to search in the contacts list. Search works on username, email, firstName, lastName, phone, jobs

page
integer <int32>

Pagination - Page number of the requested page

size
integer <int32>

Pagination - Number of elements on each page

sort
Array of strings

Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported

Responses

200

OK

401

Unauthorized

403

Forbidden

404

The organisation cannot be found

get/api/organisations/{internal-id}/contacts

Development server

https://apidev.hiveo.fr/api/organisations/{internal-id}/contacts

Test server

https://apistaging.hiveo.fr/api/organisations/{internal-id}/contacts

Production server

https://api.hiveo.fr/api/organisations/{internal-id}/contacts

Get a document revision

Get a document revision. A document revision contains all metadata relative to this document.

A revision is:

  • usable if the depositor has gone through the whole upload process
  • valid if the document has passed all validation rules
  • operational if the document is valid at the specified date
Authorizations:
path Parameters
revision
required
string

Identifier of the revision

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get/api/revisions/{revision}

Development server

https://apidev.hiveo.fr/api/revisions/{revision}

Test server

https://apistaging.hiveo.fr/api/revisions/{revision}

Production server

https://api.hiveo.fr/api/revisions/{revision}

Download revision file

Get the PDF file corresponding to this specific revision.

Authorizations:
path Parameters
revision
required
string

Identifier of the revision

header Parameters
Accept-Language
string

User locale (ex: fr-FR)

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get/api/revisions/{revision}/file

Development server

https://apidev.hiveo.fr/api/revisions/{revision}/file

Test server

https://apistaging.hiveo.fr/api/revisions/{revision}/file

Production server

https://api.hiveo.fr/api/revisions/{revision}/file

Download proof file

If it exists, get the proof file corresponding to this specific revision.

Authorizations:
path Parameters
revision
required
string

Identifier of the revision

header Parameters
Accept-Language
string

User locale (ex: fr-FR)

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get/api/revisions/{revision}/proof

Development server

https://apidev.hiveo.fr/api/revisions/{revision}/proof

Test server

https://apistaging.hiveo.fr/api/revisions/{revision}/proof

Production server

https://api.hiveo.fr/api/revisions/{revision}/proof

Send reminders to relations

Send reminders to the specified relations.

Only relations with non operational documents, or with pending contact invitations will receive reminder notifications.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the collector organisation that requests the reminds

Request Body schema: application/json

query

actualDossiersToFilter
Array of integers <int64>
categories
Array of strings
collectors
Array of strings
depositors
Array of strings
filterDossiers
Array of integers <int64>
onlyHasExempted
boolean
onlyNoRegisteredContact
boolean
onlyNotOperational
boolean
onlyOperational
boolean
providers
Array of strings
query
string

Responses

200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/api/collectors/{internal-id}/manual-reminds

Development server

https://apidev.hiveo.fr/api/collectors/{internal-id}/manual-reminds

Test server

https://apistaging.hiveo.fr/api/collectors/{internal-id}/manual-reminds

Production server

https://api.hiveo.fr/api/collectors/{internal-id}/manual-reminds

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "actualDossiersToFilter":
    [
    ],
  • "categories":
    [
    ],
  • "collectors":
    [
    ],
  • "depositors":
    [
    ],
  • "filterDossiers":
    [
    ],
  • "onlyHasExempted": true,
  • "onlyNoRegisteredContact": true,
  • "onlyNotOperational": true,
  • "onlyOperational": true,
  • "providers":
    [
    ],
  • "query": "string"
}

Get reminder history

Get the reminders history of a specific organisation.

Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the collector organisation

query Parameters
depositor
string

Hiveo internal ID (-) of the depositor organisation whose reminds history is requested

page
integer <int32>
Default: 0

Pagination - Page number of the requested page

size
integer <int32>
Default: 10

Pagination - Number of elements on each page

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get/api/collectors/{internal-id}/reminds

Development server

https://apidev.hiveo.fr/api/collectors/{internal-id}/reminds

Test server

https://apistaging.hiveo.fr/api/collectors/{internal-id}/reminds

Production server

https://api.hiveo.fr/api/collectors/{internal-id}/reminds

Get existing relations for a collector organisation

Get all your relations at once. With this resource you can:

  • Get all your relations, or a subset of them
  • Get your relations dossiers and documents statuses

Use:

  • application/zip to export relation files (*.zip)
  • application/pdf to get your relations' conformity certificates (*.pdf)
Authorizations:
path Parameters
internal-id
required
string

Hiveo internal ID (-) of the collector organisation

query Parameters
filterDossiers
string

Id of the dossiers to search for not operational relations. If not setted, will search on all selected dossiers for the relation

onlyNoRegisteredContact
string

Only get relations without active contacts

onlyHasExempted
string

Only get relations with at least one operational exempted revision

onlyOperational
string

Only get operational relations on requested dossiers

onlyNotOperational
string

Only get not operational relations on requested dossiers

categories
string

Only get relations with the specified categories

depositors
string

Only get relations corresponding to these Hiveo internal ID (-)

providers
string

Only get relations with at least one document from this external provider

query
string

Terms to search in the relation

withInactiveRelation
string

Also get inactive relations

page
integer <int32>

Pagination - Page number of the requested page

size
integer <int32>

Pagination - Number of elements on each page

sort
Array of strings

Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

header Parameters
Accept-Language
string

User locale (ex: fr-FR)

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get/api/collectors/{internal-id}/relations

Development server

https://apidev.hiveo.fr/api/collectors/{internal-id}/relations

Test server

https://apistaging.hiveo.fr/api/collectors/{internal-id}/relations

Production server

https://api.hiveo.fr/api/collectors/{internal-id}/relations

Response samples

Content type
Copy
Expand all Collapse all
{
  • "content":
    [
    ],
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "sort": { },
  • "totalElements": 0,
  • "totalPages": 0
}