Create Collaborators and Contracts 🇫🇷

Step 1: Create a Collaborator

To begin, you need to create a collaborator by using the Create Collaborator endpoint. Provide the required information as defined in our API. Note that this step only initializes the collaborator and does not finalize their profile. The HR administrator will need to complete the collaborator's profile on the PayFit application to make them ready to receive pay slips.

Endpoint

POST https://partner-api.payfit.com/companies/{companyId}/collaborators

Request Body

Include the necessary information to initialize the collaborator, such as:

{
  "firstName": "John",
  "lastName": "Doe",
  "otherName": "Middle",
  "personalEmail": "[email protected]",
  "socialSecurityNumber": "123456789012345",
  "personalAddress": {
    "streetNumber": 123,
    "addressFirstLine": "Main Street",
    "addressSecondLine": "Apt 456",
    "city": "Paris",
    "state": "Île-de-France",
    "postCode": "75001",
    "country": "FR"
  }
}

Fields

• firstName (string, required): First name of the collaborator.
• lastName (string, required): Last name of the collaborator.
• otherName (string): Additional name information of a collaborator. In France it can be the "nom d'usage", in Spain it can be the "segundo apellido", in UK it can be the "middle name".
• personalEmail (string, required): Personal email of the collaborator.
• socialSecurityNumber (string): Social security number of the collaborator. Length allowed by country: GB: 12, ES: 14, FR: 15.
• personalAddress (object): Personal address of the collaborator.
  • streetNumber (number, required): Street number.
  • addressFirstLine (string, required): First line of the address.
  • addressSecondLine (string): Second line of the address.
  • city (string, required): City.
  • state (string): State.
  • postCode (string, required): Postal code.
  • country (string, required): Country code.

Response

Upon successful creation, you will receive a collaborator ID, which will be used in subsequent steps.

Step 2: Initialize a Contract

You can optionally initialize a contract for the collaborator using the Create Contract endpoint. You need to provide the collaborator ID obtained from the previous step, along with the job title and start date.

Endpoint

POST https://partner-api.payfit.com/companies/{companyId}/collaborators/{collaboratorId}/contracts

Request Body

Include the necessary information to initialize the contract:

{
  "collaboratorId": "12345",
  "jobTitle": "Software Engineer",
  "startDate": "2023-01-01"
}

Fields

• collaboratorId (string, required): The ID of the collaborator.
• jobTitle (string, required): Job title on the contract.
• startDate (date, required): Start date of the contract in the format YYYY-MM-DD.

Response

This endpoint returns no data, just a 201 status code if successful. The contract can take 2-5min before being available.

Important Notes

1. Contract Completion: The HR administrator must complete the contract by providing additional information such as health insurance and work hours to meet all legal requirements for generating payslips.

2. Multiple Contracts: While it is technically possible to create multiple contracts for a collaborator, it is strongly recommended to avoid this during the initialization phase. It will be difficult for the HR manager to identify which contract needs to be updated. We encourage implementing a control to prevent initializing a new contract if one is already in progress. If your use case requires multiple contracts, proceed with caution and ensure proper identification and management.

3. Country Availability: Currently, this functionality is only available for France. It will be made available for Spain and the United Kingdom in the future.