This method is used to upload a document to an employee folder in our system.
Warning
This endpoint entered deprecation in July 2021. As per our deprecation policy, its sunset period started in January 2022 and retirement will occur in July 2022. Consider using the corresponding APIv2 endpoint instead.
This POST call must be encoded in multipart/form-data. All parameters must be encoded in JSON (serialized) in the POST field data, with the exception of the POST file parameter containing the binary file:
file (mandatory):
Binary file of the document to be uploaded.
external_reference (optional, deprecated): Character string, VARCHAR(255)
External document reference to help identify this document in external tools or filing systems
external_unique_id (optional): Character string, VARCHAR(255)
With the 18.8 version of Document Manager, this field has now the same behaviour as the external_reference field. If it is passed alongside external_reference then only external_unique_id is recorded. For reference, its former description was: Unique reference to the document in the filing system (for example). If included in the request, a uniqueness verification is performed in the employee folder. If a document with the same identifier has already been uploaded, the method returns an HTTP 409 conflict error
title (mandatory): Character string, VARCHAR(255)
Title of the document as displayed in UKG HR Service Delivery
Example:
Employment contract Mathieu Martin - January 2012 - Ref: 457895
document_type_id or document_type_code (mandatory): Entire (document_type_id) or character string, VARCHAR(100) (document_type_code)
Identifier of the uploaded employee type document (the list of identifiers is provided during the project phase) if document_type_id.
Uploaded employee type document (the list of identifiers is provided during the project phase) if document_type_code. The code is a string of alphanumeric characters without spaces or accents, but dashes and underscores are permitted. For example:
payslip
date (optional): Formatted character string, VARCHAR(40)
Date of the document. Corresponds to the date used in the by-date classification of the documents. If this date is not specified, the classification date used is the date the document was uploaded (i.e. the API method call date)
Format: Date ISO 8601, including hours and minutes. Example: 2012-07-16T19 :20+01: 00
document_type_metas (optional or mandatory depending on the configuration of the document type):
If the type of document requires additional parameters (classification criteria), they must be indicated in this field. Each additional field is identified by a “technical code” (a string of alphanumeric characters without spaces or accents, but dashes and underscores are permitted). It could have for value an integer, a string or a date (in ISO format, YYYY-MM-DD). The string could be a free entry or a value from a predefined list.
Example:
{ 'contract_starting_date': '2012-07-16', 'contract_end_date': '2012-07-16' }
document_type_filters (optional or mandatory depending on the configuration of the document type):
If the type of document requires custom fields (formerly referred as filters), they must be indicated in this field. Custom fields are configured by document type and share the same behaviour as the “document_type_metas” fields. Each field is identified by a “technical code” and can have for value an integer or a string. The string could be a free entry or a value from a predefined list. However they are rather used to limit access to the document as a user on UKG HR Service Delivery could have a restriction access on documents based on its values.
Example:
{ 'nh': '4', // nh étant par exemple un filtre de "Niveau hierarchique" }
employee_technical_id (mandatory): Character string, VARCHAR(50)
Technical employee identifier in our system
organization_codes (optional): List of character strings, VARCHAR(64)
List of organization codes of the document.
If this parameter is specified in the call, the document is associated with all of the organizations. Note: The employee must belong to these organizations via an active or an inactive registration reference. Otherwise, the method returns and HTTP 409 error (in other words, it is not possible to associate a document with an organization if this organization is not one of the employee’s organizations)
If this parameter is not specified, the document is associated with all of the employee’s “active” organizations for current employees or with all of the employee’s “inactive” organizations for terminated employees.
api_uploader_name (optional): Name of the uploader.
JSON view of a call (POST data parameter only):
POST /api/v1/enterprise/documents/
{
'external_unique_id': "6789678GKVGHKVGHJK",
'title': "Contrat de travail Jean Dupont Janvier 2013 - Dossier 678",
'document_type_code': "contract",
'date': "2013-01-24",
'document_type_metas': {
'date-deb-contrat': "2013-01-30"
},
'employee_technical_id': "678967896789",
'organization_codes': ['FSUD1', 'FSUD2'],
'api_uploader_name': "Mike Doug"
}
In Curl:
curl -v -X POST "https://api.novapost.net/api/v1/enterprise/documents/" \
-H "Content-type: multipart/form-data" \
-H "Accept: application/json" \
-H "X-API-KEY: XXXXXXXXXXXXXX" \
-F "[email protected]" \
-F "data={\"external_unique_id\": \"6789678GKVGHKVGHJK\",\"title\": \"Contrat de travail Jean Dupont Janvier 2013 - Dossier 678\", \"document_type_code\": \"contrat-de-travail\",\"employee_technical_id\": \"678967896789\", \"api_uploader_name\": \"Mike Doug\"}"
HTTP 201 Created: The document has been successfully uploaded
The response is encoded in JSON format with the following parameters:
id:
Identifier of the created document. Present if the creation of the process was successful (code HTTP 201 CREATED).
HTTP 201 CREATED { 'id': "678967890", }
HTTP 400 Bad Request: Invalid parameters.
List of errors in JSON format:
Each error is represented by its JSON object
{'code': 1001, 'message': 'Invalid ...'}. The error message is given as an indication (debug).
code = 1408: Mandatory parameter missing
code = 1409: Incorrect parameter (e.g., the document type code does not exist)
code = 1410: Missing document_type_id or document_type_code parameter
code = 1411: Incorrect parameter type
code = 1412: Missing parameter (for the metas)
code = 1414: Missing filter
code = 1415: Missing filter
code = 1417: Incorrect filter value
code = 1418: Missing meta
code = 1419: Meta not available for this type of document
code = 1420: Incorrect meta value
code = 1421: Invalid date
code = 1426: Error during upload to archiving system
Example:
HTTP 400 Bad Request { 'code': xxxx, 'message': "date is not a valid date" }
HTTP 409 Conflict: (if the parameter external_unique_id is passed in the call and already exists in the database).
HTTP 409 Conflict { 'code': 1428, 'message': "The document with the external_unique_id XXXXXXXXXXXXXXX already exist", }
HTTP 403 Forbidden: Authentication failed.
This method is used to upload a company document (a document not associated with a particular employee, but only to an organization) onto UKG HR Service Delivery.
Note: the URL is identical to the previous method used for uploading a document associated with an employee, but the parameters differ.
This POST call must be encoded in multipart/form-data. All parameters must be encoded in JSON (serialized) in the POST field data, with the exception of the POST file parameter containing the binary file:
file (mandatory):
Binary file of the document to be uploaded.
external_reference (optional, deprecated): Character string, VARCHAR(255)
External document reference to help identify this document in external tools or filing systems
external_unique_id (optional): Character string, VARCHAR(255)
With the 18.8 version of Document Manager, this field has now the same behaviour as the external_reference field. If it is passed alongside external_reference then only external_unique_id is recorded. For reference, its former description was: Unique reference to the document in the filing system (for example). If included in the request, a uniqueness verification is performed in the employee folder. If a document with the same identifier has already been uploaded, the method returns an HTTP 409 conflict error
title (mandatory): Character string, VARCHAR(255)
Title of the document as displayed in UKG HR Service Delivery
Example:
Employment contract Mathieu Martin - January 2012 - Ref: 457895
document_type_id or document_type_code (mandatory): Entire (document_type_id) or character string, VARCHAR(100) (document_type_code)
Identifier of the uploaded company type document (the list of identifiers is provided during the project phase) if document_type_id.
Code of the uploaded company type document (the list of identifiers is provided during the project phase) if document_type_code. The code is a string of alphanumeric characters without spaces or accents, but dashes and underscores are permitted. For example:
convention-collective [collective-agreement]
date (optional): Formatted character string, VARCHAR(40)
Date of the document. Corresponds to the date used in the by-date classification of the documents. If this date is not specified, the classification date used is the date the document was uploaded (i.e. the API method call date)
Format: Date ISO 8601, including hours and minutes. Example: 2012-07-16T19 :20+01: 00
document_type_metas (optional or mandatory depending on the configuration of the document type):
If the type of document requires additional parameters (classification criteria), they must be included in this field. Each additional field may be entire, a character string or date (in ISO format, YYYY-MM-DD), and is identified with a “technical code” (an alphanumeric character string with no spaces or accents, but dashes and underscores are permitted).
Example:
{ 'contract_starting_date': '2012-07-16', 'contract_end_date': '2012-07-16' }
document_type_filters (optional or mandatory depending on the configuration of the document type):
If the type of document requires filter attributes, they must be indicated in this field. These additional fields are configured by document type and function in the same way as the “document_type_metas” fields but are used to limit access to the uploaded document according to the access rules defined for the UKG HR Service Delivery user roles (advanced filters).
Example:
{ 'nh': '4', // nh étant par exemple un filtre de "Niveau hierarchique" }
organization_code (deprecated): Character string, VARCHAR(64)
Warning
DEPRECATED.
Please use organization_codes.
organization_codes (mandatory): List of character strings, VARCHAR(64)
Organization codes of the document.
POST /api/v1/enterprise/documents/
{
'external_unique_id': "6789678GKVGHKVGHJK",
'title': "Contrat de travail Jean Dupont Janvier 2013 - Dossier 678",
'document_type_code': "convention-collective",
'date': "2013-01-24",
'organization_codes': ['FSUD1']
}
HTTP 201 Created: The document has been successfully uploaded
The response is encoded in JSON format with the following parameters:
id:
Identifier of the created document. Present if the creation of the process was successful (code HTTP 201 CREATED).
HTTP 201 CREATED { 'id': "678967890", }
HTTP 400 Bad Request: Invalid parameters.
List of errors in JSON format:
Each error is represented by its JSON object
{'code': 1001, 'message': 'Invalid ...'}. The error message is given as an indication (debug).
code = 1408: Mandatory parameter missing
code = 1409: Incorrect parameter (e.g., the document type code does not exist)
code = 1411: Incorrect parameter type
code = 1412: Missing parameter (for the metas)
code = 1414: Missing filter
code = 1415: Missing filter
code = 1417: Incorrect filter value
code = 1418: Missing meta
code = 1419: Meta not available for this type of document
code = 1420: Incorrect meta value
code = 1421: Invalid date
code = 1426: Error during upload to archiving system
Example:
HTTP 400 Bad Request { 'code': xxxx, 'message': "date is not a valid date" }
HTTP 409 Conflict: (if the parameter external_unique_id is passed in the call and already exists in the database).
HTTP 409 Conflict { 'code': xxxx, 'message': "The document with the external_unique_id XXXXXXXXXXXXXXX already exist", }
HTTP 403 Forbidden: Authentication failed.
GET /api/v1/enterprise/documents/{document_id}/download/
Warning
Beware! This method does require an authentication with a signed request. This request takes the form of an extra parameter hash calculated on the client server.
Format is as follow:
SHA256(token, document_id, timestamp)
or
HASHMAC_SHA256(token, document_id, timestamp)
document_id (mandatory): Entire
Identifier of the document to be downloaded
timestamp (mandatory): Floating
Request generation date, in unix format with GMT timestamp in seconds (milliseconds after the decimal). Example: 1172960204.226900. The generated URL is valid for 5 minutes. Note, this timestamp must be based on a UTC+0 (GMT) date
hash (mandatory): Character string
Signature (i.e. hash SHA256, hash HASHMAC_SHA256) of the concatenation of parameters in this order: token, document_id, timestamp. This security parameter is therefore used to ensure that the request originates from an authorized application (since it is in possession of a token). When UKG HR Service Delivery receives the request, this
hashis locally recalculated and compared to that received. See the following paragraph for generation of this parameter.
hash_method (optional): List of values from among [‘sha256’, empty]
Function used for the hash parameter. If empty, the function used is HASHMAC_SHA256. Another possible value: ‘sha256’
Using the sha256 function: hash_method = sha256
import hashlib
TOKEN = 'mysecretkey'
document_id = 42
timestamp = time.time()
data = u'%s%s%s' % (TOKEN, document_id, timestamp)
built_hash = hashlib.sha256(data).hexdigest()
Using the hmac function, in other words, hash_method is not specified:
import hashlib
import hmac
TOKEN = 'mysecretkey'
document_id = 42
timestamp = time.time()
data = u'%s%s%s' % (TOKEN, document_id, timestamp)
built_hash = hmac.new(secret.encode('ascii'), msg=data.encode('utf-8'), digestmod=hashlib.sha256).hexdigest()
Thus, if the unsigned URL is:
https://api.novapost.net/api/v1/enterprise/documents/456456/download/
then the signed authenticated single-use URL has the following format:
https://api.novapost.net/api/v1/enterprise/documents/456456/download/?timestamp={timestamp}&hash={hash}&hash_method=sha256