Typescript SDK

🚧
Limited endpoint coverage
This SDK currently supports one operation: retrieving applicants (GET /applicants), through getJobApplications(). It does not cover the rest of the Partner API — including jobs, easy apply, documents, analytics and webhooks. For those, call the REST API directly; the API Reference lists every endpoint.

What is @apploitech/apploi-client?

The official TypeScript client for Apploi’s Partner API. It wraps the generated Fern SDK with a developer-friendly layer that adds native TypeScript types, input validation, and a consistent error model. This means faster integration, fewer runtime surprises, and a cleaner DX from local development to production.

Features

✅ Native TypeScript Types - Use number, Date, and enums instead of strings
✅ Input Validation - Catch errors before making API calls
✅ Strongly-Typed Responses - Full TypeScript interfaces with IDE autocomplete
✅ Better Error Handling - Custom exception hierarchy with detailed error information
✅ Bundled SDK - Includes the Fern-generated SDK, no additional dependencies needed
✅ Developer-Friendly - Intuitive API that follows TypeScript best practices

Installation

npm install @apploitech/apploi-client

or with yarn:

yarn add @apploitech/apploi-client

Quick Start

import { ApploiClient } from "@apploitech/apploi-client";

// Initialize the client
const client = new ApploiClient({
  apiKey: "your-api-key-here",
  baseUrl: "https://partners.apploi.com", // Optional, this is the default
});

// Get job applications with native types
const applications = await client.getJobApplications({
  jobId: 12345, // number, not string!
  limit: 50, // number, not string!
  updatedAfter: new Date("2024-01-01"), // Date object, not string!
});

// Strongly-typed response
console.log(applications.applicants[0].name); // Full TypeScript support
console.log(applications.pagination.total); // IDE autocomplete works
console.log(applications.pagination.hasMore); // Know exactly what fields exist

💡 See examples.ts for comprehensive usage examples including pagination, error handling, and advanced features.

API Reference

Client Initialization

import { ApploiClient, ApploiClientConfig } from "@apploitech/apploi-client";

const config: ApploiClientConfig = {
  apiKey: "your-api-key", // Required - API key for authentication
  authorization: "your-auth-token", // Optional - not required by the API
  baseUrl: "https://api.example.com", // Optional - uses default if not provided
  timeout: 30000, // Optional - timeout in milliseconds
  customHeaders: {
    // Optional - additional headers
    "X-Custom-Header": "value",
  },
};

const client = new ApploiClient(config);

// Or use minimal configuration (recommended):
const client = new ApploiClient({
  apiKey: "your-api-key",
});

Getting Job Applications

import {
  GetJobApplicationsParams,
  ApplicationStatus,
} from "@apploitech/apploi-client";

const params: GetJobApplicationsParams = {
  // All parameters are optional and strongly-typed
  jobId: 12345, // number or string
  teamId: 67890, // number or string
  status: ApplicationStatus.SCREENING, // Enum value
  updatedAfter: new Date("2024-01-01"), // Date object
  updatedBefore: new Date("2024-12-31"), // Date object
  limit: 50, // number (1-100)
  offset: 0, // number (>= 0)
  includeArchived: false, // boolean
};

try {
  const result = await client.getJobApplications(params);

  // Access strongly-typed response
  for (const applicant of result.applicants) {
    console.log(`${applicant.name} - ${applicant.status}`);
    console.log(`Applied: ${applicant.createdAt}`);
    console.log(`Email: ${applicant.email}`);
  }

  // Pagination information
  console.log(`Total: ${result.pagination.total}`);
  console.log(`Has more: ${result.pagination.hasMore}`);
} catch (error) {
  // Handle errors (see Error Handling section)
}

Working with Application Status

import { ApplicationStatus } from "@apploitech/apploi-client";

// Use the enum for type safety
const status = ApplicationStatus.HIRED;

// Available statuses:
// - ApplicationStatus.APPLIED
// - ApplicationStatus.SCREENING
// - ApplicationStatus.INTERVIEWING
// - ApplicationStatus.REFERENCE_CHECK
// - ApplicationStatus.OFFER_EXTENDED
// - ApplicationStatus.HIRED
// - ApplicationStatus.REJECTED
// - ApplicationStatus.WITHDRAWN
// - ApplicationStatus.ON_HOLD
// - ApplicationStatus.UNKNOWN (fallback for unrecognized values)

Error Handling

The adapter provides a custom exception hierarchy for better error handling:

import {
  ApploiValidationError,
  ApploiAuthenticationError,
  ApploiAPIError,
  ApploiResponseParseError,
} from "@apploitech/apploi-client";

try {
  const result = await client.getJobApplications({ limit: 2000 }); // Invalid!
} catch (error) {
  if (error instanceof ApploiValidationError) {
    // Parameter validation failed
    console.error(`Field ${error.field} is invalid:`, error.message);
    console.error("Provided value:", error.value);
  } else if (error instanceof ApploiAuthenticationError) {
    // 401 or 403 status code
    console.error("Auth failed:", error.statusCode, error.message);
  } else if (error instanceof ApploiAPIError) {
    // Other API errors
    console.error("API error:", error.statusCode, error.message);
    console.error("Response:", error.response);
  } else if (error instanceof ApploiResponseParseError) {
    // Failed to parse API response
    console.error("Parse error:", error.message);
    console.error("Raw response:", error.rawResponse);
  }
}

Type Definitions

JobApplication

interface JobApplication {
  id: string;
  jobId: string;
  teamId?: string;
  status?: ApplicationStatus;
  firstName?: string;
  lastName?: string;
  name: string;
  email?: string;
  phone?: string;
  createdAt?: Date;
  updatedAt?: Date;
  source?: string;
  address?: Address;
  resume?: Attachment;
  coverLetter?: Attachment;
  attachments?: Attachment[];
  notes?: string;
  tags?: string[];
  score?: number;
  isPriority?: boolean;
  // ... and more fields
}

ApplicantsList

interface ApplicantsList {
  applicants: JobApplication[];
  pagination: {
    total: number;
    limit: number;
    offset: number;
    hasMore: boolean;
  };
}

Validation Rules

The adapter validates all inputs before making API calls:

limit: Must be between 1 and 100
offset: Must be >= 0
IDs: Can be numbers or strings, automatically converted
Dates: Accept Date objects or ISO strings, converted to YYYY-MM-DD format
Status: Must be a valid ApplicationStatus enum value

Advanced Usage

Access the Underlying SDK

If you need to access the raw Fern SDK for any reason:

const sdkClient = client.getSdkClient();
// Use raw SDK methods if needed

Custom Validators

You can also use the validators directly:

import {
  validateLimit,
  validateId,
  validateAndConvertDate,
} from "@apploitech/apploi-client";

// Validate parameters before use
const limit = validateLimit(50); // Returns "50"
const id = validateId(12345, "jobId"); // Returns "12345"
const date = validateAndConvertDate(new Date(), "startDate"); // Returns "YYYY-MM-DD"

Building the Project

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run linter
npm run lint

# Format code
npm run format