HIVEO API (1.3)

Download OpenAPI specification:Download

Introduction

Hiveo works as a network interconnecting companies.

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

2021-04-07

Change the signature of object usage retrieved from the endpoint GET /api/available-usages, by replacing the integer id with the string of characters code.

2021-02-15

In a near future we will allow depositors to create a derogation revision from few document-types, as they can today with an exempted one. The derogation will be more restrictive than the exemption.

To make it visible as a special kind of revisions, we already added :

  • onlyHasDerogation filter in GET /api/collectors/{internal-id}/relations
  • hasDerogation field in DocumentState and in Dossier
  • derogation field in Revision

2020-08-10

  • Add 2 new endpoints to dynamically expose Hiveo document types and usages.

2020-07-09

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

2020-01-03

First version of our collector API.

Overview

Environments

We provide 3 different environments:

  1. Our Development environment, only accessible to us.
  2. Our Test environment, used for testing our API. It is accessible on weekdays between 7:30 a.m. and 8:30 p.m. (CET).
  3. 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 ;
    1. You will be able to retrieve the new relation using the relations endpoint ;
  5. If you send a reminder, the email won’t be sent ;
    1. You will be able to retrieve the reminder using the reminder history endpoint for this depositor.

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

How to check your actions on our test environment

If you create new relations or close existing ones, you can check the result using the relations endpoint:

  1. Closed relations won’t be returned, unless you use certain filters ;
  2. New relations will be returned.

If you invite a new internal user to your organisation, you can check the result using the contacts endpoint.

If you send a reminder to a depositor, you can check the result using the reminder history endpoint.

Differences between our environments

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

To access to the documentation of a specific version, use /version/v<version number>.html.

For example, for version 1.0: /version/v1.0.html.

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.

⚠️ Limits

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

Core concepts

Hiveo interconnects companies, and let them create relations between them. Employees of these companies are invited to create an account on Hiveo and are called users. Users can choose to expose themselves as contacts for all or part of their company work sites.

⚠️ Countries managed by Hiveo

Hiveo only manage French companies from now.

Employees are invited to join their company on Hiveo:

  1. By their relations’ contacts,
  2. By their internal coworkers.

Once they have registered on Hiveo, they are able to declare themselves as contacts for some or all or their company work sites.

A user becomes contact for a work site:

  1. when a collector creates a relation with this work site and explicitely add her as contact,
  2. by manually declaring herself contact for this work site.

A user can manage the work sites she is contact for, add some, remove others…

Hiveo is a network: A company’s information, documents and contacts are mutualised for all its relations.

Once a company has created a relation with a supplier work site, it can see if this relation has active contacts. Active contacts are users that have registered to Hiveo and declared themselves as contacts for this work site.

An active contact on a work site:

  • manages documents for all collector organisations in relation
  • receives notifications for this work site (reminders, new relations…)
  • appears as contacts in the work site page

Example: Active contacts

In this example, C1-SIRET1, a work site of company1, has created a relation with C2-SIRET2, a work site of company2, and invited user2 from company2 to join Hiveo.

user2 has:

  1. created her account on Hiveo,
  2. been automatically added to C2-SIRET2 by Hiveo, as she has been invited on this work site,
  3. has decided to only expose herself as contact on C2-SIRET1, another company2 work site, and has manually detached herself from C2-SIRET2.

Thus C2-SIRET2 no longer has any active contact.

user2 is still able to add some of the documents collected by company1, as company2 dossiers are mutualised accross all work sites, but won’t receive any notifications regarding C2-SIRET2, such as reminders, and won’t be able to add documents specifically required by company1.

To solve this situation:

  1. company1 can detect through the (C1-SIRET1, C2-SIRET2) relation that C2-SIRET2 has no active contact, and can then decide to invite another user from company2,
  2. user2 can invite one of her colleagues on Hiveo to manage C2-SIRET2.

Organisations, collectors, depositors and relations

Companies and their work sites are called 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 are French, so they have the FR country code.

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 headquarter has the Hiveo ID FR-84122605300012):

    "country": "FR"
    "nationalId": "84122605300012"
    "internalId": "FR-84122605300012"

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

To sum up:

  1. Organisations can be collector, depositor, or both,
  2. A relation is between a collector and a depositor,
  3. Hiveo internal ID is built like that: <Country code>-<National ID>,
  4. Relations are created between work sites.

Here you can find a conceptual representation of the Hiveo relation model. It is meant to explain our main notions, rather than precisely describe our model definitions (which you can find in the endpoints description):

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.

Example 1: Create relations without providing any contact

Example 2: Create relations while providing a contact

Example 3: Detect that a relation has no more active contact

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 for this organisation,
  2. receives notifications for this organisation,
  3. can see this organisation dossiers, and add any missing document.

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

Hiveo automatically remind relations with incomplete dossiers (automatic document reminders).

When sending a manual reminders (whereas by API or by our web application), Hiveo:

  1. Sends document reminders to relations with active contacts and incomplete dossiers,
  2. Sends invitation reminders to not-registered contacts of relations with incomplete dossiers,
  3. Does not send any reminder to relations with complete dossiers.

Dossiers and documents

Documents

Each depositor uploads documents on Hiveo. A Hiveo document:

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

Dossiers

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.

Revisions

Versions of documents are called revisions.

A same PDF file can be linked to several revisions, if it corresponds to 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),
  • operational if the document has passed all validation rules: it has a start validity date, and an end validity date. It is operational between these 2 dates.

Model

Here you can find a conceptual representation of the Hiveo document model. It is meant to explain our main notions, rather than precisely describe our model definitions (which you can find in the endpoints description):

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 endpoint description for details.

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

💡 Default - Active relations 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": "30/09/2020",
      "valid_to_date": "30/03/2021",
      "verification_proof": "8489ab80-a242-4eee-af5e-feb18547a43a",
      "fault_name": "",
      "issue_date": "06/11/2020",
      "code_nature": "AVG",
      "workforce": "3",
      "payroll": "18756.0",
      "reference_date": "30/09/2020",
      "verification_code": "ZNYMT1G8UGXTWHI",
      "reference_period_text": "mois de septembre 2020",
      "page_count": "2"
    }
  }
}

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

Hiveo lets you know if your relations are actually legally active, at risk or closed.

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.

Inactive relations won’t be returned by the relations endpoint, unless you use a specific filter.

Example 5: Check if a relation has active contacts

Hiveo lets you know if your relations have active contacts. A relation with no active contact means that none of the invited users has already join Hiveo: No one will be able to upload documents for this organisation.

You can check if one of your relations has active contacts in the relation 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
      }
    }
  }
}

The withActive attribute lets you know if at least one active contact is available for this relation.

Example 6: Deactivate an existing relation

You can deactivate an existing relation by API, for example if you do not work with this company anymore.

Inactive relations won’t be returned by the relations endpoint, unless you use a specific filter.

To close an existing relation, use:

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

Body contains:

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

⚠️ Custom information

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

⚠️ OFA & ALG

ALG is the former acronym of OFA, and is still used in our APIs.

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

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

The response contains a depositor object which includes providers information.

For example, if the depositor organisation has an account on OFA, ALG is listed in its document providers:

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

Some of its documents come from OFA, and are thus provided by ALG:

{
  "documents": [
    {
      "label": "Justificatif d'immatriculation Kbis",
      "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 /api/collectors/{internal-id}/close-relation
Relations Reopen a previously closed relation Write User POST /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

You can dynamically retrieve Hiveo configuration regarding document types, usages and dossiers using the following endpoints:

  1. GET /api/available-document-types: Retrieve all available document types, and their configuration,
  2. GET /api/available-usages: Retrieve all available usages, and their configuration.

These endpoints expose Hiveo configuration for these document types, usages and dossiers. They only return our general usages and types. Relation-specific document types configuration can NOT be retrieved this way.

⚠️ Hiveo general configuration

These endpoints do not return your collected document types and usages as a collector. These information are retrieved in the response of the /api/collectors/{internal-id}/relations endpoint.

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.

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

required
Array of objects (Guest)

Users to add to the organisation

Responses

Request samples

Content type
application/json
{
  • "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

Relations

Close or activate previous relations, invite new depositor organisations in your relations.

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
Array of objects (Guest)
internalCode
string
invitedOrganisationInternalId
string
invitingOrganisationInternalId
string

Responses

Request samples

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

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

onlyHasDerogation
string

Only get relations with at least one operational derogation 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

Response samples

Content type
{
  • "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

Request samples

Content type
application/json
{
  • "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

Request samples

Content type
application/json
{
  • "collector": "string",
  • "depositor": "string"
}

Reminders

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

Send reminders to relations

Send reminders to the specified relations.

This endpoint:

  1. send document reminders to relations with active contacts and incomplete dossiers,
  2. send invitation reminders to relations without any active contacts,
  3. does not send any reminder to relations with complete dossiers.
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
onlyHasDerogation
boolean
onlyNoRegisteredContact
boolean
onlyNotOperational
boolean
onlyOperational
boolean
providers
Array of strings
query
string

Responses

Request samples

Content type
application/json
{
  • "actualDossiersToFilter": [
    ],
  • "categories": [
    ],
  • "collectors": [
    ],
  • "depositors": [
    ],
  • "filterDossiers": [
    ],
  • "onlyHasExempted": true,
  • "onlyHasDerogation": 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

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

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

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

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

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

Get last modified revisions of a relation

Get at maximum the 99 last modified revisions of a relation. The minimum lastModifiedAfter date must be under 1 year in the past. The lastModifiedBefore date is optional (now by default)

Authorizations:
query Parameters
collector
required
string

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

depositor
required
string

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

lastModifiedAfter
required
string <date-time>

Date from which to gather revisions created or last modified after. The minimum lastModifiedAfter date must be under 1 year in the past. The date format is a local date time, for example, 2022-04-10T12:00:00

lastModifiedBefore
string <date-time>

Date to which to gather revisions created or last modified before. The lastModifiedBefore date is optional (now by default). The date format is a local date time, for example, 2022-04-10T12:00:00

Responses

Usages and document types

Available Hiveo usages and document types.

List Hiveo standard document types

Retrieve all Hiveo standard document types.

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Hiveo standard usages

Retrieve all Hiveo standard usages.

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

Request samples

Content type
application/json
{
  • "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

Request samples

Content type
application/json
{
  • "collector": "string",
  • "depositor": "string"
}

List Hiveo standard document types

Retrieve all Hiveo standard document types.

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Hiveo standard usages

Retrieve all Hiveo standard usages.

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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
Array of objects (Guest)
internalCode
string
invitedOrganisationInternalId
string
invitingOrganisationInternalId
string

Responses

Request samples

Content type
application/json
{
  • "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

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

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

required
Array of objects (Guest)

Users to add to the organisation

Responses

Request samples

Content type
application/json
{
  • "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

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

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

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

Send reminders to relations

Send reminders to the specified relations.

This endpoint:

  1. send document reminders to relations with active contacts and incomplete dossiers,
  2. send invitation reminders to relations without any active contacts,
  3. does not send any reminder to relations with complete dossiers.
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
onlyHasDerogation
boolean
onlyNoRegisteredContact
boolean
onlyNotOperational
boolean
onlyOperational
boolean
providers
Array of strings
query
string

Responses

Request samples

Content type
application/json
{
  • "actualDossiersToFilter": [
    ],
  • "categories": [
    ],
  • "collectors": [
    ],
  • "depositors": [
    ],
  • "filterDossiers": [
    ],
  • "onlyHasExempted": true,
  • "onlyHasDerogation": 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

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

onlyHasDerogation
string

Only get relations with at least one operational derogation 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

Response samples

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

Get last modified revisions of a relation

Get at maximum the 99 last modified revisions of a relation. The minimum lastModifiedAfter date must be under 1 year in the past. The lastModifiedBefore date is optional (now by default)

Authorizations:
query Parameters
collector
required
string

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

depositor
required
string

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

lastModifiedAfter
required
string <date-time>

Date from which to gather revisions created or last modified after. The minimum lastModifiedAfter date must be under 1 year in the past. The date format is a local date time, for example, 2022-04-10T12:00:00

lastModifiedBefore
string <date-time>

Date to which to gather revisions created or last modified before. The lastModifiedBefore date is optional (now by default). The date format is a local date time, for example, 2022-04-10T12:00:00

Responses