PaySpace

Use PaySpace API to manage your PaySpace account

Actions8

Overview

This node integrates with the PaySpace API, enabling users to manage various aspects of their PaySpace account programmatically. It supports a wide range of operations related to employee data, company information, payroll processing, and more. The node is particularly useful for automating HR, payroll, and employee management workflows by fetching, creating, updating, or deleting records in PaySpace.

Common scenarios include:

Retrieving collections or single records of employees, employment statuses, positions, bank details, dependants, projects, assets, custom forms, incidents, pay rates, claims, payslips, and workflow steps.
Creating or updating employee-related records such as addresses, employment statuses, positions, bank details, dependants, attachments, projects, assets, custom forms, incidents, pay rates, take-on records, recurring templates, claims, and workflow submissions.
Uploading or downloading employee photos and claim attachments.
Executing authorization to obtain access tokens.
Querying metadata or lookup values.
Managing webhooks and file uploads.

Practical examples:

Automatically update an employee’s address when a form is submitted.
Fetch all active employees as of a specific date for reporting.
Submit employee claims for approval workflows.
Download employee payslip PDFs for distribution.

Properties

Name	Meaning
Environment	Selects the PaySpace environment to query: Staging or Production.
Scope	(Only for Authorization operation) Defines the OAuth scope for the token request. Options: Full Access, Read Only, Update, Create.
Company ID	Numeric identifier of the company within PaySpace to target API requests.
Api Request	Specifies the particular API endpoint or action to perform, chosen from dynamically loaded options depending on the operation and endpoint.
Effective Date	A date-time value used to filter collections as of a certain effective date (e.g., employees, employment statuses, positions).
Employee Number	String identifier for an employee, used in some API calls like retrieving employee address.
ID	Identifier string for specific records (e.g., EmployeeId, EmployeePositionId), required for many single-record operations.
UserWorkflowStepId	Identifier for workflow step, used in workflow-related API calls.
Category	String category filter, e.g., for fetching custom forms by category.
Period	String representing a period, used in operations like updating payslip comments.
Frequency	String representing frequency, used alongside period in some operations.
Body (Raw)	JSON object containing raw data payload for create or update operations.
Add Params	Boolean flag indicating whether to add optional query parameters.
Additional Fields	Collection of optional query parameters such as orderBy, top, skip, count, select, filter, componentCodes, altLanguage, etc., to refine API queries.
This node is still in beta	Notice informing users that the node is in beta stage.

Output

The node outputs the response from the PaySpace API in the json field of the output data. The structure of this JSON depends on the specific API call made but generally includes:

Collections of records (arrays) for list endpoints.
Single record objects for get, create, update operations.
Metadata or status information for authorization and other control operations.
Binary data handling is supported for photo upload/download and PDF retrieval, where the node manages multipart/form-data requests and responses accordingly.

Dependencies

Requires an API key credential with client ID and client secret for OAuth2 authentication.
Uses Axios HTTP client for making API requests.
Uses qs library for URL-encoded form data serialization during token requests.
Supports FormData for file upload/download operations.
Requires proper configuration of credentials in n8n to authenticate against PaySpace's identity service.
Environment URLs differ between staging and production and are selected based on the "Environment" property.

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 official PaySpace API documentation.
Authentication Failures: If token retrieval fails, check that the client ID and secret are correct and that the selected scope matches the permissions granted.
Missing or Incorrect IDs: Many operations require specific record IDs; ensure these are correctly provided and correspond to existing records.
API Rate Limits or Timeouts: Large queries or frequent requests may hit API limits; consider using pagination parameters (top, skip) and handle errors gracefully.
Binary Data Handling: For photo or PDF uploads/downloads, ensure the input data format is correct and that the node has access to necessary file buffers.
Additional Parameters Misuse: When using additional query parameters, ensure they conform to OData filtering and sorting syntax as per PaySpace API guidelines.