Technical Integration Documentation

This page is the technical entry point for integration engineers and vendor-assessment teams connecting a system to TapTalent. It links every machine-readable artifact we publish — the OpenAPI (Swagger) specification and Postman collection — and summarizes the API’s protocols, JSON data structures, and supported communication methods.

Downloads

All artifacts are versioned in lockstep with this documentation and regenerated automatically whenever the API reference changes.

OpenAPI 3.1 Specification (YAML)

The complete machine-readable API contract — 32 REST operations and 14 webhook events. Canonical source of truth.

OpenAPI 3.1 Specification (JSON)

The same specification as JSON, for tooling that prefers it.

Postman Collection

Ready-to-import collection with pre-filled example requests for every endpoint, organized by resource.

Postman Environments

Production environment · Sandbox environment — base URL and API-key variables for each environment.

Your browser may render the files instead of downloading them — use “Save as” (or curl -O) to save a copy.

Swagger / OpenAPI documentation

The specification is written in OpenAPI 3.1.0 and covers the entire documented Partner API:

32 REST operations across 23 paths — Jobs, Candidates, Job Candidates, Pipelines, Custom Fields, and Custom Field Values.
14 webhook events modeled under the OpenAPI webhooks section, including envelope, per-event payload schemas, and delivery headers.
Full request/response schemas, field constraints, enumerations, and error models, with examples for every operation.

Explore in the API Playground

Every operation in the specification is browsable and executable in the interactive API Playground tab of this site — try requests against production or sandbox with your own API key.

The specification works with any standard OpenAPI tooling — Swagger UI, Swagger Editor (editor.swagger.io), Redoc, code generators (openapi-generator, swagger-codegen), and contract testing tools. Import the YAML or JSON file directly.

Postman collection

Import the collection

In Postman: Import → drop in taptalent-partner-api.postman_collection.json (or paste its URL from the download card above).

Import both environments

Import the production and sandbox environment files the same way.

Add your API key

Open the environment you want to use and paste your key into the apiKey variable (sk_live_… for production, sk_test_… for sandbox). Keys are generated in the dashboard under Account Settings → Developers.

Select the environment and send

Pick the environment in Postman’s environment selector. Every request inherits bearer authentication from the collection and resolves {{baseUrl}} from the environment.

Delete Pipeline Stage sends a JSON request body with a DELETE request (required by the API). Postman supports this natively; some other HTTP clients strip DELETE bodies — check yours if the call fails. Webhook payloads are not part of the collection (they are inbound deliveries, not callable requests); see the OpenAPI specification’s webhooks section or the Webhooks documentation.

API specifications

Aspect	Value
Protocol	REST over HTTPS (TLS)
Production base URL	`https://partner-api.taptalent.io/v1/partner`
Sandbox base URL	`https://sandbox.partner-api.taptalent.io/v1/partner`
Authentication	API key as HTTP bearer token (`Authorization: Bearer sk_live_…`)
Data format	JSON (`application/json`), UTF-8
Versioning	Path-based (`/v1`); breaking changes ship in new versions with advance notice
Rate limiting	Applied at the company level
Success status codes	`200 OK` (and `201 Created` for pipeline stage creation)
Error status codes	`400`, `401`, `403`, `404`, `429`, `500`

JSON data structure

Success responses use one of three envelope styles, by resource family — each endpoint’s exact shape is defined in the OpenAPI specification:

Resource family	Success envelope
Jobs	Bare object, e.g. `{ "jobs": [...], "totalJobs": 45 }`
Candidates, Job Candidates, Pipelines, Custom Fields	`{ "status": "success", "data": ... }`
Bulk resume upload / batch retrieval	`{ "success": true, "data": ... }`

Most errors use the canonical error envelope:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Human-readable error message",
    "details": {
      "field": "Specific validation error message"
    }
  }
}

{
  "title": "Senior Software Engineer",
  "city": "San Francisco",
  "state": "California",
  "country": "United States",
  "workMode": "REMOTE",
  "status": "ACTIVE"
}

{
  "event": "candidate.added_to_job",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": 12345,
  "data": {
    "jobId": 12345,
    "stageId": 67890,
    "candidateIds": [111, 112],
    "jobCandidateIds": [211, 212],
    "count": 2
  }
}

Authentication failures return flat shapes instead (for example { "message": "Invalid API key" }) — see Authentication and the shared 401 response in the specification.

Supported communication methods

All communication with the API is JSON over HTTPS. No SOAP, SFTP, or file-drop mechanisms are used or required.

Method	Direction	Description
Synchronous REST API	Your system → TapTalent	Request/response calls for jobs, candidates, pipelines, and custom fields. Authenticated with a bearer API key.
Webhooks (event push)	TapTalent → your system	Real-time `POST` notifications for every event type in the event catalogue to your configured HTTPS endpoint, with `X-Webhook-Event`, `X-Webhook-Timestamp`, and `X-Webhook-Key` verification headers and automatic retries (200 ms / 400 ms / 800 ms).
Bulk / batch operations	Your system → TapTalent	Asynchronous bulk resume ingestion (up to 5,000 resumes per batch) with completion signaled via webhook events and a batch status endpoint.

For managed engagements, TapTalent can additionally deliver data directly into your HRIS—see HRIS Delivery Options.

API Reference — hand-written endpoint documentation with examples
Webhooks — setup, verification, and the full event catalogue
Authentication — obtaining and using API keys
Open API Capabilities — what the platform offers for building integrations

Get Started

Authentication

API Reference

Webhooks

Integration Notes