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

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

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.

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

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

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.

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.

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

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 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, 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,
        "nbAdminProfile": 1,
        "nbMemberProfile": 1,
        "withAdmin": true
      }
    }
  }
}

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

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

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

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

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.

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

Request samples

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

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

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.

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

Request samples

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

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

Response samples

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