List, fetch, create, update, and destroy job postings (requisitions), with JSON:API filtering by status, department, location, and division, plus pagination, sorting, and related includes for departments, locations, stages, and applications.
openapi: 3.0.1
info:
title: Pinpoint API
description: >-
REST API for the Pinpoint applicant tracking system (ATS) and recruitment
platform. The API adheres to the JSON:API specification and is served on a
per-tenant basis. All requests must be made over HTTPS to
https://{subdomain}.pinpointhq.com/api/v1, where {subdomain} matches the
subdomain used to log in to Pinpoint. Authentication uses an X-API-KEY
header generated from Settings > API & Webhooks. Requests and responses use
the application/vnd.api+json media type. Not to be confused with AWS
Pinpoint (customer engagement messaging) or Pinpoint (signal / data
intelligence).
termsOfService: https://www.pinpointhq.com/legal/
contact:
name: Pinpoint Support
url: https://developers.pinpointhq.com/docs/introduction
version: '1.0'
servers:
- url: https://{subdomain}.pinpointhq.com/api/v1
description: Per-tenant Pinpoint API base URL.
variables:
subdomain:
default: acme
description: The subdomain used to log in to your Pinpoint account.
security:
- ApiKeyAuth: []
tags:
- name: Jobs
description: Job postings and requisitions.
- name: Applications
description: Candidate applications moving through hiring workflows.
- name: Applicants
description: Candidate (applicant) records.
- name: Comments
description: Comments on applications.
- name: Webhooks
description: Webhook event payloads delivered to subscriber URLs.
paths:
/jobs:
get:
operationId: listJobs
tags:
- Jobs
summary: List jobs
description: Returns a paginated list of jobs (requisitions).
parameters:
- $ref: '#/components/parameters/PageNumber'
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Sort'
- $ref: '#/components/parameters/Include'
- name: filter[status]
in: query
description: Filter by job status (e.g. open, closed, archived, draft).
schema:
type: string
- name: filter[department_id]
in: query
schema:
type: integer
- name: filter[location_id]
in: query
schema:
type: integer
- name: filter[division_id]
in: query
schema:
type: integer
responses:
'200':
description: A list of jobs.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JobCollection'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createJob
tags:
- Jobs
summary: Create job
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JobSingleWrite'
responses:
'201':
description: The created job.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JobSingle'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/jobs/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getJob
tags:
- Jobs
summary: Fetch job
parameters:
- $ref: '#/components/parameters/Include'
responses:
'200':
description: The requested job.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JobSingle'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateJob
tags:
- Jobs
summary: Update job
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JobSingleWrite'
responses:
'200':
description: The updated job.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JobSingle'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
delete:
operationId: destroyJob
tags:
- Jobs
summary: Destroy job
responses:
'204':
description: The job was deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/applications:
get:
operationId: listApplications
tags:
- Applications
summary: List applications
parameters:
- $ref: '#/components/parameters/PageNumber'
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Sort'
- $ref: '#/components/parameters/Include'
- name: filter[job_id]
in: query
schema:
type: integer
- name: filter[stage_id]
in: query
schema:
type: integer
responses:
'200':
description: A list of applications.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/ApplicationCollection'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createApplication
tags:
- Applications
summary: Create application
description: >-
Creates an application for a job. Supports candidate name, email, phone,
address, LinkedIn URL, a CV/document upload as a base64 payload, and
custom attributes.
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/ApplicationSingleWrite'
responses:
'201':
description: The created application.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/ApplicationSingle'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/applications/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getApplication
tags:
- Applications
summary: Fetch application
description: >-
Fetch a single application. Related offers, candidates, jobs, and stages
can be requested with the include parameter, and computationally
expensive fields such as attachments via extra_fields.
parameters:
- $ref: '#/components/parameters/Include'
- name: extra_fields[offers]
in: query
description: Request expensive fields such as attachments on included offers.
schema:
type: string
responses:
'200':
description: The requested application.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/ApplicationSingle'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateApplication
tags:
- Applications
summary: Update application
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/ApplicationSingleWrite'
responses:
'200':
description: The updated application.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/ApplicationSingle'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
delete:
operationId: destroyApplication
tags:
- Applications
summary: Destroy application
responses:
'204':
description: The application was deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/candidates:
get:
operationId: listCandidates
tags:
- Applicants
summary: List candidates (applicants)
parameters:
- $ref: '#/components/parameters/PageNumber'
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Sort'
- $ref: '#/components/parameters/Include'
responses:
'200':
description: A list of candidates.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/CandidateCollection'
'401':
$ref: '#/components/responses/Unauthorized'
/candidates/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getCandidate
tags:
- Applicants
summary: Fetch candidate (applicant)
description: >-
Fetch a candidate. Uploaded documents can be read through the
attachments relationship using the extra_fields parameter.
parameters:
- $ref: '#/components/parameters/Include'
- name: extra_fields[candidates]
in: query
description: Request expensive fields such as attachments.
schema:
type: string
responses:
'200':
description: The requested candidate.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/CandidateSingle'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateCandidate
tags:
- Applicants
summary: Update candidate (applicant)
description: >-
Update a candidate, including uploading documents via a
documents_base64 array attribute.
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/CandidateSingleWrite'
responses:
'200':
description: The updated candidate.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/CandidateSingle'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/comments:
get:
operationId: listComments
tags:
- Comments
summary: List comments
parameters:
- $ref: '#/components/parameters/PageNumber'
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Include'
- name: filter[application_id]
in: query
schema:
type: integer
responses:
'200':
description: A list of comments.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/CommentCollection'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createComment
tags:
- Comments
summary: Create comment
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/CommentSingleWrite'
responses:
'201':
description: The created comment.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/CommentSingle'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/comments/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getComment
tags:
- Comments
summary: Fetch comment
responses:
'200':
description: The requested comment.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/CommentSingle'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
description: >-
API key generated in Settings > API & Webhooks > API Keys. Sent with
every request as the X-API-KEY header. Missing or invalid keys return
HTTP 401.
parameters:
ResourceId:
name: id
in: path
required: true
description: The resource identifier.
schema:
type: string
PageNumber:
name: page[number]
in: query
description: The page of results to return. Defaults to 1.
schema:
type: integer
default: 1
PageSize:
name: page[size]
in: query
description: Number of results per page (0-1000). Defaults to 100.
schema:
type: integer
minimum: 0
maximum: 1000
default: 100
Sort:
name: sort
in: query
description: >-
Comma-separated sort fields (e.g. created_at, -updated_at). Prefix with
a hyphen for descending order.
schema:
type: string
Include:
name: include
in: query
description: >-
Comma-separated list of relationship paths to side-load, with dot
notation for nested relationships (JSON:API includes).
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Errors'
NotFound:
description: The requested resource was not found.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Errors'
UnprocessableEntity:
description: Validation failed for the submitted resource.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Errors'
schemas:
Errors:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type: string
title:
type: string
detail:
type: string
source:
type: object
properties:
pointer:
type: string
ResourceIdentifier:
type: object
properties:
type:
type: string
id:
type: string
JobAttributes:
type: object
properties:
title:
type: string
description:
type: string
status:
type: string
description: e.g. open, closed, archived, draft.
employment_type:
type: string
workplace_type:
type: string
description: onsite, hybrid, or remote.
compensation_minimum:
type: number
compensation_maximum:
type: number
compensation_currency:
type: string
visibility:
type: string
opened_at:
type: string
format: date-time
deadline_at:
type: string
format: date-time
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
Job:
type: object
properties:
type:
type: string
example: jobs
id:
type: string
attributes:
$ref: '#/components/schemas/JobAttributes'
relationships:
type: object
additionalProperties: true
JobSingle:
type: object
properties:
data:
$ref: '#/components/schemas/Job'
JobSingleWrite:
type: object
properties:
data:
type: object
properties:
type:
type: string
example: jobs
id:
type: string
attributes:
$ref: '#/components/schemas/JobAttributes'
JobCollection:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Job'
meta:
$ref: '#/components/schemas/PaginationMeta'
ApplicationAttributes:
type: object
properties:
first_name:
type: string
last_name:
type: string
email:
type: string
phone:
type: string
linkedin_url:
type: string
cv_base64:
type: string
description: Base64-encoded CV/document supplied on create.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
Application:
type: object
properties:
type:
type: string
example: applications
id:
type: string
attributes:
$ref: '#/components/schemas/ApplicationAttributes'
relationships:
type: object
additionalProperties: true
ApplicationSingle:
type: object
properties:
data:
$ref: '#/components/schemas/Application'
ApplicationSingleWrite:
type: object
properties:
data:
type: object
properties:
type:
type: string
example: applications
id:
type: string
attributes:
$ref: '#/components/schemas/ApplicationAttributes'
relationships:
type: object
additionalProperties: true
ApplicationCollection:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Application'
meta:
$ref: '#/components/schemas/PaginationMeta'
CandidateAttributes:
type: object
properties:
first_name:
type: string
last_name:
type: string
email:
type: string
phone:
type: string
linkedin_url:
type: string
documents_base64:
type: array
description: Base64-encoded documents to upload on update.
items:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
Candidate:
type: object
properties:
type:
type: string
example: candidates
id:
type: string
attributes:
$ref: '#/components/schemas/CandidateAttributes'
relationships:
type: object
additionalProperties: true
CandidateSingle:
type: object
properties:
data:
$ref: '#/components/schemas/Candidate'
CandidateSingleWrite:
type: object
properties:
data:
type: object
properties:
type:
type: string
example: candidates
id:
type: string
attributes:
$ref: '#/components/schemas/CandidateAttributes'
CandidateCollection:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Candidate'
meta:
$ref: '#/components/schemas/PaginationMeta'
CommentAttributes:
type: object
properties:
body:
type: string
created_at:
type: string
format: date-time
Comment:
type: object
properties:
type:
type: string
example: comments
id:
type: string
attributes:
$ref: '#/components/schemas/CommentAttributes'
relationships:
type: object
additionalProperties: true
CommentSingle:
type: object
properties:
data:
$ref: '#/components/schemas/Comment'
CommentSingleWrite:
type: object
properties:
data:
type: object
properties:
type:
type: string
example: comments
attributes:
$ref: '#/components/schemas/CommentAttributes'
relationships:
type: object
additionalProperties: true
CommentCollection:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Comment'
meta:
$ref: '#/components/schemas/PaginationMeta'
PaginationMeta:
type: object
properties:
total_count:
type: integer
page_count:
type: integer