Projects & Distributions API¶

Overview of the process
Create a project
- URL
- Arguments
- Sample call
- Response
Create a distribution
- URL
- Arguments
- Sample call
- Response
Validate a project

Overview of the process ¶

To send and archive documents in batch, a distribution project must be created. A distribution project consists of one or more spools of documents to be distributed (the distributions), with each spool itself consisting of a series of named documents of the same type following a formatted determined in advance during the settings phase.

A typical project creation through the API includes the following calls:

Create a new project with the POST /api/v1/distrib_projects/ method
Add one or more distributions to this newly created project with the POST /api/v1/distrib_projects/:project_id/distributions/ method
The distributions in the project are automatically processed when uploaded
(optional) Receive callbacks for each completed distribution
(optional) Receive a callback when the project is ready for validation (each distribution has been succesfully completed). A URL is sent for a user to control the result of the processing
Validate the project with the PUT /projects/:project_id/validate/ method to display documents in UKG HR Service Delivery, in the employee vaults, and send the paper campaigns.

Create a project ¶

This method creates a new project

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.

URL ¶

POST /api/v1/distrib_projects/
    Accept: application/json
    Content-Type: application/x-www-form-urlencoded
    X-API-KEY: xxxxxxxxxxxxxxxxxxxxxxxxxxx

Arguments ¶

The POST is in form encoded data (Content-Type: application/x-www-form-urlencoded):

Parameter	Description	Type	mandatory	Exemple
name	The name of the project	`VARCHAR`	`mandatory`	May 2014 Paystubs
validation_option	Identifier of validation options configuration.	`INTEGER`	`mandatory`	0
delivery_paper_conf	Identifier of delivery paper configuration.	`VARCHAR` (alphanumeric lower case with “-” and “_”)	`mandatory`	no-paper
regroup_paper_mailing	Parameter used to group paper shipments. When sending multiple documents, one of the spools must be labeled as the main spool, the corresponding documents will then appear first in their respective packages	`BOOLEAN`	no	true
group	code identifying the distribution group that can access this project.	`VARCHAR`	no	‘code’
package_sent_to_orgs	True to send it to the employee’s organisations, False to send it to the adress defined in the project.	`BOOLEAN`	no	false
tech_id	Manager sender’s tech_id	`VARCHAR`	no	‘abc123’
auto_validate	True if you want to auto-validate the projects if all its distributions succeeded.	`BOOLEAN`	no	true
package_first_name	Project address for mailing.	`VARCHAR`	no	Project’s address for mailing: first name.
package_last_name	Project address for mailing.	`VARCHAR`	no	Project’s address for mailing: last name.
package_address	Project address for mailing.	`VARCHAR`	no	Project’s address for mailing: address.
package_address_2	Project address for mailing.	`VARCHAR`	no	Project’s address for mailing: address 2.
package_address_3	Project address for mailing.	`VARCHAR`	no	Project’s address for mailing: address 3.
package_postcode	Project address for mailing.	`VARCHAR`	no	Project’s address for mailing: postcode.
package_city	Project address for mailing.	`VARCHAR`	no	Project’s address for mailing: city.
package_country	Project address for mailing.	`VARCHAR`	no	Project’s address for mailing: country.
package_contact	Project address for mailing.	`VARCHAR`	no	Project’s address for mailing: telephone number or email to contact in case of error.

Sample call ¶

POST /api/v1/distrib_projects/
    Content-Type: application/x-www-form-urlencoded
    X-API-KEY: xxxxxxxxxxxxxxxxxxxxxxxxxxx

Request body:

{
  'name': "May 2014 Paystubs",
  'validation_option': 0
  'delivery_paper_conf': 'code'
  'regroup_paper_mailing': true,
  'group': 'code',
  'package_sent_to_orgs': false,
  'tech_id': 'abc123',
  'auto_validate': true,
  'package_first_name': "Jean",
  'package_last_name': "Dupond",
  'package_address': "12 rue Jean Jaurès",
  'package_address2':"",
  'package_address3': "",
  'package_postcode': "75001",
  'package_city': "Paris",
  'package_country': "FR",
  'package_contact': "person@domain.com",
}

Curl example:

$ curl -H "X-API-KEY: XXXXXXXXXXXXXXX" -X POST \
> --data "name=Project&validation_option=0\
> &delivery_paper_conf=code" \
> https://example.com/api/v1/distrib_projects/

Response ¶

Success¶

The response is encoded in the JSON format with the following parameters:

Parameter	Description	Type	Example
project_id	The id of the project (to be used to create `Distributions` on this project)	`INTEGER`	1456151
msg	Message about Information about the `project`	`VARCHAR`	Project created on xxxx.peopledoc.com

HTTP 200 OK

{
  "msg": "Project created on xxxx.peopledoc.com",
  "project_id": 6796789
}

Errors¶

HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{
    'errors': 'Project sender with tech id foo does not exists'
}

HTTP/1.1 400 BAD REQUEST

{
    'errors': {
        'delivery_paper_conf': ['Select a valid choice. That choice
                                 is not one of the available
                                 choices.']
    }
}

Create a distribution ¶

This method adds a new distribution in a project

URL ¶

Warning

Since a file is transmitted in this method, this POST call must be encoded in multipart/form-data.

POST /api/v1/distrib_projects/:project_id/distributions/
    Accept: application/json
    Content-Type: multipart/form-data
    X-API-KEY: xxxxxxxxxxxxxxxxxxxxxxxxxxx

Arguments ¶

Warning

All parameters must be encoded in form data:

Parameter	Description	Type	mandatory	Example
project_id (in the url)	The `Distribution` is added to the corresponding `project`	`INTEGER`	`mandatory`	42
source_file	Binary file of the distribution (ZIP of PDFs / TXT / PDF containing all documents / …)	`FILE`	`mandatory`	`ZIP of PDFs (download)`
name	NAme of the distribution spool, displayed in the interface and used to identify the spool within a distribution project.	`VARCHAR`	`mandatory`	`Paystubs` or `Timecards`
distribution_type_type	Identifier of the distribution type value. ‘code’ is the most likely.	`VARCHAR`	`mandatory`	‘code’
distribution_type_value	Value of the distribution type code, defined by the client with the project manager.	`VARCHAR`	`mandatory`	‘payslips’

Sample call ¶

POST /api/v1/distrib_projects/6796789/distributions/
    Accept: application/json
    Content-Type: application/json
    X-API-KEY: xxxxxxxxxxxxxxxxxxxxxxxxxxx

Data parameter of the request body:

{
  'name': 'May 2014 Paystubs',
  'distribution_type_type': 'code',
  'distribution_type_value': 'bsi',
  'source_file': @path/file.pdf
}

Curl example:

$ curl -H “X-API-KEY: XXXXXXXXXXXXXXX” > -H ‘Content-type:multipart/form-data’ > -F “name=Distrib” -F “distribution_type_type=code” > -F “distribution_type_value=bsi” > -F ‘source_file=@path/file.pdf;type=application/pdf’ > https://example.com/api/v1/distrib_projects/42/distributions/

Response ¶

Success¶

The response is encoded in the JSON format with the following parameters:

Parameter	Description	Type	Exemple
distribution_id	The id of the distribution	`INTEGER`	42
msg	Information	`VARCHAR`	‘Distribution May 2014 Paystubs is creating’

HTTP 200 Created

{
  "msg": "Distribution May 2014 Paystubs is creating",
  "distribution_id": 42
}

Errors¶

HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{
    'errors': 'Project not found'
}

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
    'errors': {
        'name': ['This field is required.']
    }
}

Validate a project ¶

This method creates a new project

URL ¶

POST /projects/6796789/validate/
    Accept: application/json
    Content-Type: application/json
    X-API-KEY: xxxxxxxxxxxxxxxxxxxxxxxxxxx

Arguments ¶

(The body of this POST is empty)

Parameter	Description	Type	mandatory	Exemple
project_id (GET)	The id of the `project` to validate	`INTEGER`	`mandatory`	6796789

Sample call ¶

POST /projects/6796789/validate/
    Accept: application/json
    Content-Type: application/json
    X-API-KEY: xxxxxxxxxxxxxxxxxxxxxxxxxxx