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

Organisations

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.
2. The french Hiveo headquarter has the national ID 84122605300012.
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"

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

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

Example 1: Synchronize your relations directory

To get all your suppliers at once, use:

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

This call can be used to synchronize the first time, or once in a while to force a full synchronisation.

Then to only get modifications since your last call, use:

    GET /api/collectors/{internal-id}/relations?fromLastModifiedDate={previous call date, such as 2019-04-01T17:32:28Z}

Reference

Our Swagger file is available here.

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

Through the API you can:

• 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,
• And much more.

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

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…).

We provide 2 different environnements:

1. Our staging environnment, used for testing our API
2. Our production environnement, used for… production :)

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

All endpoints of the Hiveo API require authentication.

We accept the following Oauth2 grant types:

Many of our API resources use pagination.

You can select whatever you want to receive using page and size parameters.

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.

Contacts related resources

Document Files related resources

Invitations related resources

Organisations related resources

Reminders related resources

Relations related resources