Overview
The PaySpace node integrates with the PaySpace API to manage various aspects of a PaySpace account, primarily focusing on employee and company data management. It supports multiple operations including looking up values, managing employee records, employment statuses, positions, bank details, dependants, claims, workflows, payslips, and more.
For the Lookup Values operation under the Default resource, the node queries specific lookup data from the PaySpace system for a given company. This is useful when you need to retrieve reference or configuration data such as lists of statuses, categories, or other enumerations that are used within PaySpace.
Typical use cases include:
- Fetching dropdown options or reference data dynamically for forms or automation workflows.
- Retrieving configuration or metadata needed to drive further API calls or business logic.
- Integrating PaySpace lookup data into other systems or reports.
Example: You want to get a list of all employment statuses available for a company to populate a selection field in an HR application.
Properties
| Name | Meaning |
|---|---|
| Environment | Selects which environment to query: "Staging" (test environment) or "Production" (live environment). |
| Company ID | The numeric identifier of the company in PaySpace for which the lookup values are requested. |
| Api Request | The specific API endpoint related to the lookup operation. Options are loaded dynamically based on the operation and endpoint selected. |
| Effective Date | (Shown only for certain APIs) The date as of which the data should be effective. Useful for time-sensitive collections like employment statuses or positions. |
| Employee Number | (Shown only for some APIs) The employee number associated with the request. |
| ID | (Shown only for some APIs) Identifier used by certain API requests, e.g., EmployeeId or EmployeePositionId. |
| UserWorkflowStepId | (Shown only for workflow-related APIs) Identifier for a user workflow step. |
| Category | (Shown only for custom form category APIs) The category string to filter custom forms. |
| Period | (Shown only for payslip comment update) The period value from a company run lookup. |
| Frequency | (Shown only for payslip comment update) The frequency value from a company frequency lookup. |
| Body (Raw) | (Shown only for create/update APIs) Raw JSON body containing fields to send in the request payload. |
| Add Params | Boolean flag indicating whether to add optional additional query parameters. |
| Additional Fields | Optional collection of query parameters to refine the request, including: - Order By: Specifies sorting order. - Top: Limits number of items returned. - Skip: Number of items to skip. - Count: Return count only. - Select: Fields to return. - Filter: OData filter expression. - componentCodes: Comma-separated list of component codes. - altLanguage: Whether to retrieve payslip components in alternative language. |
| This node is still in beta | Notice displayed to inform users about the node's beta status. |
Output
The node outputs the JSON response received from the PaySpace API call corresponding to the lookup values request. The structure of the json output depends on the specific API endpoint queried but generally includes:
- Collections of lookup data objects relevant to the requested resource.
- Metadata about the collection if applicable (e.g., counts, paging info).
- For binary data endpoints (not typical for lookup values), the node would handle binary content accordingly, but this operation focuses on JSON data.
The output is wrapped in an array of items, each containing a json property with the API response data.
Dependencies
- Requires an API key credential for authenticating with the PaySpace API.
- Uses OAuth2 token retrieval internally via client credentials flow.
- Depends on external libraries such as Axios for HTTP requests and qs for query string serialization.
- Requires proper configuration of the environment (staging or production) and valid company IDs.
- The node dynamically loads API endpoint options based on the selected operation.
Troubleshooting
- Invalid Operation Error: If an unsupported operation or API endpoint is selected, the node throws an "Invalid Operation" error. Ensure the correct operation and API request are chosen.
- Authentication Failures: Errors during token retrieval or authorization indicate invalid or missing API credentials. Verify the API key and secret are correctly configured.
- Missing Required Parameters: Some API calls require mandatory parameters like Company ID, ID, or Effective Date. Omitting these will cause errors.
- API Rate Limits or Network Issues: Standard HTTP errors may occur due to network problems or API rate limiting. Implement retry logic or check API usage quotas.
- Incorrect Query Parameters: Using invalid filters or select fields can cause API errors. Refer to the PaySpace API documentation for valid OData expressions.