--- updatedAt: 2026-06-29T09:41:37.000Z agentTools: projectIndex: https://developers.payfit.io/llms.txt --- # Create a Collaborator 🌍 Create a collaborator and return its ID. The created collaborator won't have a contract, and therefore won't appear in the collaborators list in the PayFit app. In order to create a contract, use the [create contract endpoint](https://developers.payfit.io/reference/post_contract). \ **Required scopes**: *collaborators: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": { "post": { "operationId": "POST_collaborator", "summary": "Create a Collaborator 🌍", "description": "Create a collaborator and return its ID.\nThe created collaborator won't have a contract, and therefore won't appear in the collaborators list in the PayFit app.\nIn order to create a contract, use the [create contract endpoint](https://developers.payfit.io/reference/post_contract).\n\n\\\n**Required scopes**: *collaborators:write*", "tags": [ "Collaborator" ], "parameters": [ { "in": "path", "name": "companyId", "schema": { "type": "string" }, "required": true, "description": "The id of the company" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name of the employee." }, "lastName": { "type": "string", "description": "Last name of the employee." }, "otherName": { "type": "string", "description": "Additional name information of an employee. 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": { "type": "string", "description": "Personal email of the employee." }, "socialSecurityNumber": { "type": "string", "description": "Social security number of the employee. Length allowed by country: GB: 12, ES: 14, FR: 15" }, "personalAddress": { "type": "object", "description": "Personal address of the employee.", "properties": { "streetNumber": { "type": "number", "example": 123 }, "addressFirstLine": { "type": "string", "example": "Avenue des Champs Elysées" }, "addressSecondLine": { "type": "string", "example": "Appartement 123" }, "city": { "type": "string", "example": "Paris" }, "state": { "type": "string", "example": "Île-de-France" }, "postCode": { "type": "string", "example": "75008" }, "country": { "type": "string", "x-enum-name": "CountryCodeEmployeeManagement", "example": "FR", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AN", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BU", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CS", "CU", "CV", "CW", "CX", "CY", "CZ", "DD", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FQ", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "HV", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "JT", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MI", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NH", "NI", "NL", "NO", "NP", "NQ", "NR", "NT", "NU", "NZ", "OM", "PA", "PC", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PU", "PW", "PY", "PZ", "QA", "RE", "RH", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SU", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TP", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VD", "VE", "VG", "VI", "VN", "VU", "WF", "WK", "WS", "XK", "YD", "YE", "YT", "YU", "ZA", "ZM", "ZR", "ZW" ] } }, "required": [ "streetNumber", "addressFirstLine", "city", "postCode", "country" ] }, "birthInformation": { "type": "object", "description": "Birth information of the employee.", "properties": { "birthDate": { "type": "string", "description": "Date of birth of the employee. The birth date of the employee in YYYY-MM-DD format. Must be in the past.", "format": "date" }, "birthPlace": { "type": "string", "description": "Place of birth of the employee." }, "birthCountry": { "type": "string", "x-enum-name": "CountryCodeEmployeeManagement", "example": "FR", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AN", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BU", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CS", "CU", "CV", "CW", "CX", "CY", "CZ", "DD", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FQ", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "HV", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "JT", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MI", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NH", "NI", "NL", "NO", "NP", "NQ", "NR", "NT", "NU", "NZ", "OM", "PA", "PC", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PU", "PW", "PY", "PZ", "QA", "RE", "RH", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SU", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TP", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VD", "VE", "VG", "VI", "VN", "VU", "WF", "WK", "WS", "XK", "YD", "YE", "YT", "YU", "ZA", "ZM", "ZR", "ZW" ], "description": "Country of birth of the employee." } }, "required": [ "birthDate" ] }, "personalPhoneNumber": { "type": "string", "description": "Personal phone number of the employee." }, "numberOfChildren": { "type": "number", "description": "The number of children must be an integer between 0 and 20.", "minimum": 0, "maximum": 20 }, "gender": { "type": "string", "description": "Gender of the employee.", "enum": [ "MALE", "FEMALE" ] }, "inviteCollaborator": { "type": "boolean", "description": "Whether to send an invitation email to the collaborator to access the PayFit platform. This is a beta feature and is only available for some customers for now.", "default": false } }, "required": [ "firstName", "lastName", "personalEmail" ] } } } }, "responses": { "201": { "description": "The collaborator ID.", "content": { "application/json": { "schema": { "title": "collaborator", "type": "object", "additionalProperties": false, "required": [ "collaboratorId" ], "properties": { "collaboratorId": { "type": "string" } } }, "examples": { "collaborator": { "summary": "An example of collaborator's ID", "value": { "collaboratorId": "6fe3a703-89f5-414d-8190-88f0d80435a3" } } } } } }, "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: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": "Collaborator" } ] } ```