Problem Description

We are seeking a developer with experience in Freshworks (Freshsales/Freshdesk) APIs and Replit to help us pull three key fields—ClientID, First Name, and Last Name—into our Replit-based project. We have an existing environment set up, but we’re encountering recurring authentication and permission issues (403/500 errors). The goal is to establish a reliable and secure integration that fetches these specific fields from Freshworks and makes them available in our Replit application without errors.

Acceptance Criteria

Successful Connection

The integration can authenticate with Freshworks and retrieve data without encountering 403 or 500 errors.

A simple “Verify Connection” step is provided to confirm the API credentials and domain are valid.

Data Retrieval

The system is able to fetch the ClientID, First Name, and Last Name fields from the Freshworks API (e.g., from contacts or leads), and store them in a usable format (JSON object, array, etc.) within the Replit project.

Error Handling & Logging

Clear error messages and logging are implemented so that any authentication or data-fetch issues can be easily diagnosed.

If a pull fails, the application displays a meaningful message instead of crashing or returning a generic error.

Documentation

High-level setup instructions and code comments are provided so future developers can maintain and update the integration.

Environment variable usage is explained (e.g., how to store and update the API key safely in Replit).

Technical Details

Environment:

Replit-based project (likely Node.js or Python).

Freshworks (Freshsales/Freshdesk) API with a custom domain (e.g., allegro.ellerca.com/crm/sales) and token-based authentication.

Required Features:

Endpoint(s) to retrieve ClientID, First Name, Last Name from Freshworks.

Secure storage of API credentials (Replit environment variables).

Optionally, a “Verify Connection” endpoint or button to test the credentials before attempting data sync.

Key Considerations:

Must handle potential permission issues (403 Forbidden) or internal server errors (500).

Must confirm the correct authentication method (Authorization: Token token=<API_KEY>) vs. other Freshworks products (Basic Auth).

Should provide minimal, well-structured code that can be easily extended.

Deliverables:

Working code snippet or small module that can be dropped into the Replit project.

Documentation explaining setup, usage, and troubleshooting steps.