--- updatedAt: 2026-06-29T09:41:37.000Z agentTools: projectIndex: https://developers.payfit.io/llms.txt --- # Create a Contract 🇫🇷 Create a basic contract on a collaborator and return its ID. Important notes: 1. **Contract completion**: the created contract won't be finalized, and the employee won't be available for payroll while their information is not set by an admin in the PayFit app. 2. **Multiple Contracts**: While it is technically possible to create multiple contracts for an employee, 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. \ **Required scopes**: *collaborators:contracts:write* # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Partner API", "description": "An API to let third parties communicate with PayFit", "version": "1.0" }, "servers": [ { "url": "https://partner-api.payfit.com", "description": "The PayFit API production server" } ], "paths": { "/companies/{companyId}/collaborators/{collaboratorId}/contracts": { "post": { "operationId": "POST_contract", "summary": "Create a Contract 🇫🇷", "description": "Create a basic contract on a collaborator and return its ID.\nImportant notes:\n1. **Contract completion**: the created contract won't be finalized, and the employee won't be available for payroll while their information is not set by an admin in the PayFit app.\n2. **Multiple Contracts**: While it is technically possible to create multiple contracts for an employee, 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.\n3. **Country availability**: Currently, this functionality is only available for France. It will be made available for Spain and the United Kingdom in the future.\n\n\\\n**Required scopes**: *collaborators:contracts:write*", "tags": [ "Contract" ], "parameters": [ { "in": "path", "name": "companyId", "schema": { "type": "string" }, "required": true, "description": "The id of the company" }, { "in": "path", "name": "collaboratorId", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "The id of the collaborator" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobTitle": { "type": "string", "description": "Job title on the contract.", "example": "Software Engineer" }, "startDate": { "type": "string", "format": "date", "description": "Start date of a contract in the format YYYY-MM-DD.", "example": "2021-07-18" } }, "required": [ "jobTitle", "startDate" ] } } } }, "responses": { "201": { "description": "This endpoint returns no data. The contract can take 2-5min before being available.", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "title": "error", "type": "object", "additionalProperties": false, "properties": { "error": { "type": "string", "description": "A human readable error" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "string", "additionalProperties": true } ] }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "error" ] }, "examples": { "error": { "summary": "An example of an error message", "value": { "code": 400, "error": "Bad request", "details": "Field \"id\" is required." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "title": "error", "type": "object", "additionalProperties": false, "properties": { "error": { "type": "string", "description": "A human readable error" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "string", "additionalProperties": true } ] }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "error" ] }, "examples": { "error": { "summary": "An example of an error message", "value": { "code": 401, "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "title": "error", "type": "object", "additionalProperties": false, "properties": { "error": { "type": "string", "description": "A human readable error" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "string", "additionalProperties": true } ] }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "error" ] }, "examples": { "error": { "summary": "An example of an error message", "value": { "code": 403, "error": "Forbidden action", "details": "Missing scope \"contracts:read\"." } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "title": "error", "type": "object", "additionalProperties": false, "properties": { "error": { "type": "string", "description": "A human readable error" }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "string", "additionalProperties": true } ] }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "error" ] }, "examples": { "error": { "summary": "An example of an error message", "value": { "code": 404, "error": "Ressource not found", "details": "The provided id is wrong" } } } } } } }, "security": [ { "partner-api-oauth": [ "collaborators:contracts:write" ] } ] } } }, "components": { "securitySchemes": { "partner-api-oauth": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://oauth.payfit.com/authorize", "tokenUrl": "https://oauth.payfit.com/token", "scopes": { "contracts:read": "Allow to read contracts information", "collaborators:contracts:write": "Allow to create contracts on a collaborator", "contracts:payslips:read": "Allow to read payslips", "contracts:time-information:read": "Allow to read time related information of contracts", "pension:read": "Allow to read pension documents", "collaborators:read": "Read general information of collaborators.", "collaborators:write": "Allow to create collaborators.", "collaborators:contracts:read": "Read contract information of collaborators.", "collaborators:management:read": "Read information about organisation and management.", "collaborators:meal-vouchers:read": "Read meal vouchers information of collaborators.", "collaborators:personal:read": "Read personal data of collaborators.", "collaborators:social-security:read": "Read the social security identifiers of collaborators.", "collaborators:legal-identity:read": "Read the legal identity information of collaborators.", "collaborators:bank-info:read": "Allow to read the bank info of collaborators.", "accounting:read": "Allow to read company accounting information", "payment-files:read": "Allow to read company payment file information", "time:read": "Allow to read time data", "time:write": "Allow to write time data", "health-insurance:read": "Allow to read health insurance contracts", "health-insurance:write": "Allow to write health insurance contracts" } } } } } }, "tags": [ { "name": "Contract" } ] } ```