Overview
This node integrates with the PaySpace API to manage employee-related data within a PaySpace account. It supports a wide range of operations on employee records, such as retrieving collections or single records of employees, employment statuses, positions, bank details, dependants, attachments, projects, pay rates, claims, workflows, payslips, and more. The node is useful for automating HR, payroll, and employee management tasks by programmatically accessing and modifying employee information.
Common scenarios include:
- Fetching employee lists or specific employee details.
- Creating, updating, or deleting employee records and related entities like positions or bank details.
- Uploading or downloading employee photos.
- Managing employee claims and workflows.
- Retrieving payslip data and comments.
- Handling custom forms and incident management related to employees.
Practical example:
- Automatically update an employee's address record when a form is submitted.
- Retrieve all active employees as of a certain date for payroll processing.
- Upload an employee's photo from a file storage system.
Properties
| Name | Meaning |
|---|---|
| Environment | Selects the environment to query: "Staging" or "Production". |
| Company ID | Numeric identifier of the company in PaySpace to operate on. |
| Endpoint Collection Name or ID | Collection of endpoints related to the operation (e.g., basicInformation, payrollProcessing). Choose from list or specify via expression. |
| Endpoint Name or ID | Specific endpoint related to the operation within the selected collection. Choose from list or specify via expression. |
| Api Request | Specific API request related to the operation and endpoint. Choose from list or specify via expression. |
| Effective Date | Date/time value used for queries that require an effective date filter (e.g., fetching employees as of a date). |
| Employee Number | String identifier for an employee, used in some API calls like getting an employee address. |
| ID | Identifier string for various API operations; could be EmployeeId, EmployeePositionId, or other IDs depending on the API called. |
| UserWorkflowStepId | Workflow step ID used in workflow-related API calls. |
| Category | Category string used for filtering custom forms. |
| Period | Period string used in payslip comment updates. |
| Frequency | Frequency string used in payslip comment updates. |
| Body (Raw) | JSON object containing raw data assignments for create or update operations. Fields depend on the specific API endpoint and can be referenced from PaySpace API documentation. |
| Add Params | Boolean flag indicating whether to add optional additional query parameters. |
| Additional Fields | Optional collection of query parameters to refine requests, including: - Order By (string) - Top (number): limit number of items returned - Skip (number): offset for results - Count (boolean): return count only - Select (string): fields to return - Filter (string): OData filter expression - componentCodes (string): comma-separated component codes - altLanguage (boolean): retrieve payslip components in alternative language |
| This node is still in beta | Notice field indicating the node is in beta status. |
Output
The node outputs JSON data representing the response from the PaySpace API for the requested operation. The structure varies depending on the API call but generally includes:
- Collections of employee-related records (arrays of objects).
- Single employee or related entity records (objects).
- Metadata or status information for operations like creation, update, or deletion.
If the operation involves binary data (e.g., downloading employee photos or payslip PDFs), the node handles the binary content accordingly, allowing further processing or saving.
Dependencies
- Requires an API key credential with client ID and client secret for authentication against PaySpace.
- Uses OAuth2 token retrieval from PaySpace identity endpoints.
- Depends on external libraries such as Axios for HTTP requests and qs for query string serialization.
- Requires n8n credentials configuration for the API key.
- The node dynamically constructs URLs based on environment selection (staging or production).
Troubleshooting
- Invalid Operation Error: Occurs if an unsupported or misspelled operation or API request is specified. Verify the operation and API request names against the available options.
- Authentication Failures: Ensure the API key credentials (client ID and secret) are correctly configured and valid. Check network connectivity to the PaySpace identity server.
- Missing Required Parameters: Some API calls require mandatory parameters like Company ID, Employee ID, or Effective Date. Make sure these are provided.
- API Rate Limits or Timeouts: Large data requests may time out or hit rate limits. Use pagination parameters (
top,skip) to limit data size. - Incorrect JSON in Body (Raw): For create or update operations, ensure the JSON body is well-formed and matches the expected schema from PaySpace API documentation.
- Binary Data Handling: When downloading files (photos, PDFs), ensure subsequent nodes handle binary data properly.