> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taptalent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Technical Integration Documentation

> Machine-readable API specifications, Postman collection, data structures, and supported communication methods for the TapTalent Partner API

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.

<CardGroup cols={2}>
  <Card title="OpenAPI 3.1 Specification (YAML)" icon="file-code" href="/api-reference/openapi.yaml">
    The complete machine-readable API contract — 32 REST operations and 14 webhook events.
    Canonical source of truth.
  </Card>

  <Card title="OpenAPI 3.1 Specification (JSON)" icon="brackets-curly" href="/api-reference/openapi.json">
    The same specification as JSON, for tooling that prefers it.
  </Card>

  <Card title="Postman Collection" icon="paper-plane" href="/postman/taptalent-partner-api.postman_collection.json">
    Ready-to-import collection with pre-filled example requests for every endpoint, organized by
    resource.
  </Card>

  <Card title="Postman Environments" icon="gears">
    [Production environment](/postman/taptalent-partner-api.production.postman_environment.json)
    · [Sandbox environment](/postman/taptalent-partner-api.sandbox.postman_environment.json)
    — base URL and API-key variables for each environment.
  </Card>
</CardGroup>

<Tip>
  Your browser may render the files instead of downloading them — use "Save as" (or `curl -O`) to
  save a copy.
</Tip>

## 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.

<Card title="Explore in the API Playground" icon="play" href="/api-playground/jobs/list-jobs">
  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.
</Card>

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

<Steps>
  <Step title="Import the collection">
    In Postman: **Import** → drop in `taptalent-partner-api.postman_collection.json` (or paste its
    URL from the download card above).
  </Step>

  <Step title="Import both environments">
    Import the production and sandbox environment files the same way.
  </Step>

  <Step title="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](https://client.taptalent.io/dashboard) under Account Settings → Developers.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  `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](/webhooks/overview).
</Note>

## 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:

<CodeGroup>
  ```json Error envelope theme={null}
  {
    "error": {
      "code": "INVALID_REQUEST",
      "type": "validation_error",
      "message": "Human-readable error message",
      "details": {
        "field": "Specific validation error message"
      }
    }
  }
  ```

  ```json Sample request — POST /jobs theme={null}
  {
    "title": "Senior Software Engineer",
    "city": "San Francisco",
    "state": "California",
    "country": "United States",
    "workMode": "REMOTE",
    "status": "ACTIVE"
  }
  ```

  ```json Sample webhook delivery theme={null}
  {
    "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
    }
  }
  ```
</CodeGroup>

Authentication failures return flat shapes instead (for example `{ "message": "Invalid API key" }`)
— see [Authentication](/authentication/api-keys) 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](/webhooks/events) 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](/technical-integration/hris-delivery).

## Related pages

* [API Reference](/api-reference/overview) — hand-written endpoint documentation with examples
* [Webhooks](/webhooks/overview) — setup, verification, and the full event catalogue
* [Authentication](/authentication/api-keys) — obtaining and using API keys
* [Open API Capabilities](/technical-integration/open-api-capabilities) — what the platform
  offers for building integrations