Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.1.0
info:
title: KarmaCheck API
description: 'All requests to the KarmaCheck API require a JSON Web Token (JWT) in the Authorization
header. For an overview of the API and its authentication method, refer to the following topics:
- [API basics](docs/overview/apis/api-overview.md)
- [Authentication](docs/overview/apis/authentication.md)
- [Environments](docs/overview/apis/environments.md)
- [Status codes and errors](docs/overview/apis/errors.md)'
version: '1.0'
contact:
name: KarmaCheck
email: customersuccess@karmacheck.com
x-apievangelist-provenance:
assembled: '2026-08-23'
method: searched
note: Reassembled verbatim from the 69 per-operation OpenAPI 3.1.0 YAML documents KarmaCheck publishes
inside the markdown twins of its public API reference (https://developer.karmacheck.com/api-reference/<op>.md).
Each page embeds a complete, single-operation slice of KarmaCheck's own openapi.json; the 69 slices
merged with ZERO conflicting definitions. No content was authored, inferred, or padded by API Evangelist.
KarmaCheck's consolidated export at https://developer.karmacheck.com/background-check-api/api-reference/openapi.json
is login-gated (HTTP 302 to /login), so this reassembly is the only machine-readable form of the contract
reachable without credentials.
source_index: https://developer.karmacheck.com/sitemap.xml
slices_merged: 69
conflicts: 0
servers:
- description: Stage
url: https://api-stage.karmacheck.io
- description: Prod
url: https://api.karmacheck.io
security:
- JWT: []
tags:
- name: Authentication
- name: Cases
- name: Candidate onboarding
- name: Secure documents
- name: Packages
- name: Services
- name: Users
- name: Companies
- name: Partner integrations
paths:
/auth/api:
post:
tags:
- Authentication
summary: Authenticate API client
description: Authenticates an API client with KarmaCheck so that they can access the KarmaCheck
system.
operationId: post-auth-api
requestBody:
content:
application/json:
schema:
type: object
x-examples:
Example 1:
apiKey: 03c703eb-56cc-46f6-bb63-afb3e302d1bf
clientAccessToken: ffb3c8ee-412d-43e5-975a-355e3cc54cf9
required:
- apiKey
- clientAccessToken
properties:
apiKey:
type: string
description: A unique key that identifies the partner in the KarmaCheck system. If you
are building an API integration with KarmaCheck, contact your Account Manager for
an `apiKey`. Whether you are creating an integration for your own company's use, for
ordering checks on behalf of mutual customers of yourself and KarmaCheck, or for both,
you will receive one `apiKey`.
clientAccessToken:
type: string
description: 'A secret that grants an API partner access to a specific group of a company.
The combination of an `apiKey` and a `clientAccessToken` generates a `token` for that
group. If you''re building an integration to order checks for:
- **Your own company:** Contact your Account Manager to get a `clientAccessToken`
for each group you wish to order checks for over the API.
- **A mutual customer:** Contact that mutual customer for them to give you `clientAccessToken`s
associated with your `apiKey`.'
examples:
Example:
value:
apiKey: 03c703eb-56cc-46f6-bb63-afb3e302d1bf
clientAccessToken: ffb3c8ee-412d-43e5-975a-355e3cc54cf9
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Authentication'
examples: {}
'403':
description: Forbidden
security: []
/case/id/{caseId}/cancel:
parameters:
- schema:
type: string
name: caseId
in: path
required: true
description: the case you'd like to cancel
post:
tags: []
summary: Cancel a case
operationId: post-case-id-caseId-cancel
responses:
'200':
description: OK
'401':
description: Unauthorized
'404':
description: Returned if case is not found
content: {}
'422':
description: Unprocessable Entity (WebDAV)
content:
application/json:
schema:
type: object
properties:
message:
type: string
error:
type: string
statusCode:
type: integer
x-examples:
Example 1:
message: Service cannot be canceled.
error: Unprocessable Entity
statusCode: 422
examples:
Example 1:
value:
message: Cannot cancel a case that has already started.
error: Unprocessable Entity
statusCode: 422
Example 2:
value:
message: Unable to cancel case.
error: Unprocessable Entity
statusCode: 422
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
message:
type: string
error:
type: string
statusCode:
type: integer
x-examples:
Example 1:
message: Service cannot be canceled.
error: Unprocessable Entity
statusCode: 422
examples:
Example 1:
value:
message: An error has occurred while canceling the case
error: Internal Server Error
statusCode: 500
/case/id/{caseId}/services/cancel:
parameters:
- schema:
type: string
name: caseId
in: path
required: true
description: The case containing the service you would like to cancel
post:
tags: []
summary: Cancel Case Service
operationId: post-case-id-caseId-service-cancel
requestBody:
content:
application/json:
schema:
type: object
x-examples:
Example 1:
serviceIds:
- '{{Service}}'
required:
- serviceIds
properties:
serviceIds:
type: array
items:
type: string
examples:
Example 1:
value:
serviceIds:
- AAAAAA-AAAAAAA-AAAAAAA-AAAAAAA
responses:
'200':
description: OK
'401':
description: Unauthorized
'404':
description: Returned if case is not found
content:
application/json:
schema:
type: object
properties: {}
'422':
description: Unprocessable Entity (WebDAV)
content:
application/json:
schema:
type: object
properties:
message:
type: string
error:
type: string
statusCode:
type: integer
x-examples:
Example 1:
message: Service cannot be canceled.
error: Unprocessable Entity
statusCode: 422
examples:
Service cannot be canceled:
value:
message: Service cannot be canceled.
error: Unprocessable Entity
statusCode: 422
SSN Trace required:
value:
message: SSN Trace is required when County, State, or Federal Criminal Search are
ordered.
error: Unprocessable Entity
statusCode: 422
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
message:
type: string
error:
type: string
statusCode:
type: integer
x-examples:
Example 1:
message: An error has occurred while canceling the case
error: Internal Server Error
statusCode: 500
examples:
Example 1:
value:
message: An error has occurred while canceling the case
error: Internal Server Error
statusCode: 500
/case/id/{caseId}/canadadisclosure/{language}:
parameters:
- schema:
type: string
name: caseId
in: path
required: true
description: The ID of a case.
- $ref: '#/components/parameters/language'
post:
tags:
- Candidate onboarding
summary: Acknowledge Canada Disclosure
description: Submits acknowledgement of a Canada Disclosure document for tracking and auditing purposes.
This action creates a case data record with the provided information. The system records the acknowledgment
and generates a downloadable PDF file of the acknowledged disclosure.
operationId: post-case-id-caseId-canadadisclosure-language
parameters:
- name: language
in: path
required: true
schema:
type: string
description: The language code (e.g. en-US)
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LegalAcknowledgmentDisclosure'
responses:
'200':
description: OK
'403':
description: Forbidden
'404':
description: The case was not found.
'422':
description: The case doesn't have the specified disclosure service, or the candidate already
acknowledged it.
'500':
description: Internal Server Error
get:
tags:
- Candidate onboarding
summary: Get Canada Disclosure
description: Retrieves a Canada Disclosure document to present to the candidate so that the candidate
can acknowledge and continue the onboarding process. If the candidate has already acknowledged
the disclosure, the response will indicate this and provide a valid `caseDataId` so that the details
of the previous acknowledgement can be retrieved. This can also be used to determine whether the
candidate can skip this specific disclosure step if they leave and then continue their onboarding
later or on another device, for example.
operationId: get-case-id-caseId-canadadisclosure-language
parameters:
- name: language
in: path
required: true
schema:
type: string
description: The language code (e.g. en-US)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- alreadyAck
- title
- body
- authorizationStatement
- authorizationObject
properties:
alreadyAck:
type: boolean
description: True if the candidate already acknowledged the disclosure; false otherwise.
title:
type: string
description: Escaped HTML.
header:
type: string
description: Escaped HTML.
body:
type: string
description: Escaped HTML.
authorizationStatement:
type: string
description: Escaped HTML.
authorizationObject:
type: object
required:
- sections
properties:
header:
type: string
selectionType:
type: string
enum:
- single
- multi
sections:
type: array
items:
type: object
required:
- selectionValue
properties:
title:
type: string
selectionValue:
type: string
description: The postback value when calling the corresponding acknowledge
endpoint.
example: signature
body:
type: string
caseDataId:
type: string
description: Returned only if `alreadyAck` is true.
format: uuid
signature:
type: string
description: Returned only if `alreadyAck` is true. For candidates who onboarded using
KarmaCheck's onboarding experience, this is the value that the candidate entered
into the signature input field on the legal step, which might not be exactly the
same as the name that the case was ordered under.
examples:
Example 1:
value:
alreadyAck: false
title: <div>Canada Disclosure Acknowledgment and Authorization for Background Check</div>
header: <div>Disclosure regarding background investigation and investigative consumer
reports, a summary of your rights under the Fair Credit Reporting Act</div>
body: <div><p><span>I acknowledge receipt of the separate documents entitled DISCLOSURE
REGARDING BACKGROUND INVESTIGATION, A SUMMARY OF YOUR RIGHTS UNDER THE FAIR CREDIT
REPORTING ACT and the DISCLOSURE FOR INVESTIGATIVE CONSUMER REPORT and certify that
I have read and understand those documents. </span></p><p><span>In connection with
your employment application with Example Company (the “Company”), this notice is
intended to inform you that a consumer report(s) (also known as “a background check”)
may be obtained on you from a consumer reporting agency for employment purposes.
The reports may contain information about you relating to your criminal information
or history, driving and/or motor vehicle records, education and/or employment history,
social media, or other background checks, inclusive of but not necessarily limited
to records and information from </span><span>any law enforcement agency, administrator,
state or federal agency, institution, school or university (public or private),
information service bureau, employer, or insurance company</span><span>. </span><span>I
agree that a facsimile ("fax"), electronic or photographic copy of this
Authorization shall be as valid as the original.</span></p><p><span>The report(s)
is being prepared by our background screening vendor, KarmaCheck, Inc. and its associated
partners or vendors.</span></p><p><span>The scope of this notice and below authorization
is not limited to the present and, if you are hired, will continue throughout the
course of your employment and allow the Company to conduct future screenings for
retention, promotion or reassignment, as permitted by law and unless revoked by
you in writing.</span></p></div>
authorizationStatement: '<div><p><b><u><span>AUTHORIZATION</span></u></b></p><p>By
signing below, you authorize the obtaining of a consumer report by the Company at
any time after receipt of this authorization and throughout the course of your employment,
as described above.</p><form><p><input type=''checkbox'' readonly='''' ##SEND_REPORT##
style=''-fs-checkbox-style: check;'' /><label>Check the box if you would like to
receive a copyÏ of the investigative consumer report, free of charge, if one is
obtained by the Company.</label></p><p>Signature</p><p><input type=''text'' readonly=''''
value=''''/></p></form></div>'
authorizationObject:
sections:
- title: AUTHORIZATION
selectionValue: signature
body: By signing below, you authorize the obtaining of a consumer report by the
Company at any time after receipt of this authorization and throughout the course
of your employment, as described above.
'403':
description: Forbidden
'404':
description: The case was not found.
'422':
description: The case does not have the specified disclosure as a requirement.
'500':
description: Internal Server Error
/case/id/{caseId}/customdisclosure/{language}:
parameters:
- schema:
type: string
name: caseId
in: path
required: true
description: The ID of a case.
- $ref: '#/components/parameters/language'
post:
tags:
- Candidate onboarding
summary: Acknowledge Custom Disclosure
description: Submits acknowledgement of a Custom Disclosure document for tracking and auditing purposes.
This action creates a case data record with the provided information. The system records the acknowledgment
and generates a downloadable PDF file of the acknowledged disclosure.
operationId: post-case-id-caseId-customdisclosure-language
parameters:
- name: language
in: path
required: true
schema:
type: string
description: The language code (e.g. en-US)
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LegalAcknowledgmentDisclosure'
responses:
'200':
description: OK
'403':
description: Forbidden
'404':
description: The case was not found.
'422':
description: The case doesn't have the specified disclosure service, or the candidate already
acknowledged it.
'500':
description: Internal Server Error
get:
tags:
- Candidate onboarding
summary: Get Custom Disclosure
description: Retrieves a Custom Disclosure document to present to the candidate so that the candidate
can acknowledge and continue the onboarding process. If the candidate has already acknowledged
the disclosure, the response will indicate this and provide a valid `caseDataId` so that the details
of the previous acknowledgement can be retrieved. This can also be used to determine whether the
candidate can skip this specific disclosure step if they leave and then continue their onboarding
later or on another device, for example.
operationId: get-case-id-caseId-customdisclosure-language
parameters:
- name: language
in: path
required: true
schema:
type: string
description: The language code (e.g. en-US)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- alreadyAck
- title
- body
- authorizationStatement
- authorizationObject
properties:
alreadyAck:
type: boolean
description: True if the candidate already acknowledged the disclosure; false otherwise.
title:
type: string
description: Escaped HTML.
header:
type: string
description: Escaped HTML.
body:
type: string
description: Escaped HTML.
authorizationStatement:
type: string
description: Escaped HTML.
authorizationObject:
type: object
required:
- sections
properties:
header:
type: string
selectionType:
type: string
enum:
- single
- multi
sections:
type: array
items:
type: object
required:
- selectionValue
properties:
title:
type: string
selectionValue:
type: string
description: The postback value when calling the corresponding acknowledge
endpoint.
example: signature
body:
type: string
caseDataId:
type: string
description: Returned only if `alreadyAck` is true.
format: uuid
signature:
type: string
description: Returned only if `alreadyAck` is true. For candidates who onboarded using
KarmaCheck's onboarding experience, this is the value that the candidate entered
into the signature input field on the legal step, which might not be exactly the
same as the name that the case was ordered under.
examples:
Example 1:
value:
alreadyAck: false
title: <div>Custom Disclosure Acknowledgment and Authorization for Background Check
(custom)</div>
header: <div>Disclosure regarding background investigation and investigative consumer
reports, a summary of your rights under the Fair Credit Reporting Act</div>
body: <div><p><span>custom disclosure - I acknowledge receipt of the separate documents
entitled DISCLOSURE REGARDING BACKGROUND INVESTIGATION, A SUMMARY OF YOUR RIGHTS
UNDER THE FAIR CREDIT REPORTING ACT and the DISCLOSURE FOR INVESTIGATIVE CONSUMER
REPORT and certify that I have read and understand those documents. </span></p><p><span>In
connection with your employment application with Example Company (the “Company”),
this notice is intended to inform you that a consumer report(s) (also known as “a
background check”) may be obtained on you from a consumer reporting agency for employment
purposes. The reports may contain information about you relating to your criminal
information or history, driving and/or motor vehicle records, education and/or employment
history, social media, or other background checks, inclusive of but not necessarily
limited to records and information from </span><span>any law enforcement agency,
administrator, state or federal agency, institution, school or university (public
or private), information service bureau, employer, or insurance company</span><span>.
</span><span>I agree that a facsimile ("fax"), electronic or photographic
copy of this Authorization shall be as valid as the original.</span></p><p><span>The
report(s) is being prepared by our background screening vendor, KarmaCheck, Inc.
and its associated partners or vendors.</span></p><p><span>The scope of this notice
and below authorization is not limited to the present and, if you are hired, will
continue throughout the course of your employment and allow the Company to conduct
future screenings for retention, promotion or reassignment, as permitted by law
and unless revoked by you in writing.</span></p></div>
authorizationStatement: '<div><p><b><u><span>AUTHORIZATION</span></u></b></p><p>By
signing below, you authorize the obtaining of a consumer report by the Company at
any time after receipt of this authorization and throughout the course of your employment,
as described above.</p><form><p><input type=''checkbox'' readonly='''' ##SEND_REPORT##
style=''-fs-checkbox-style: check;'' /><label>Check the box if you would like to
receive a copyÏ of the investigative consumer report, free of charge, if one is
obtained by the Company.</label></p><p>Signature</p><p><input type=''text'' readonly=''''
value=''''/></p></form></div>'
authorizationObject:
sections:
- title: AUTHORIZATION
selectionValue: signature
body: By signing below, you authorize the obtaining of a consumer report by the
Company at any time after receipt of this authorization and throughout the course
of your employment, as described above.
'403':
description: Forbidden
'404':
description: The case was not found.
'422':
description: The case does not have the specified disclosure as a requirement.
'500':
description: Internal Server Error
/case/id/{caseId}/esig/{language}:
parameters:
- schema:
type: string
name: caseId
in: path
required: true
description: The ID of the case.
- $ref: '#/components/parameters/language'
post:
tags:
- Candidate onboarding
summary: Acknowledge E-Signature
description: Submits acknowledgement of the e-Signature for tracking and auditing purposes. This
action creates a case data record with the provided information. The system records the acknowledgment
and generates a PDF file of the e-Signature document, which includes the candidate's acknowledgment
and is available for download.
operationId: post-case-id-caseId-esig-language
parameters:
- name: language
in: path
required: true
schema:
type: string
description: The language code (e.g. en-US)
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LegalAcknowledgmentSignature'
examples:
Example 1:
value:
signatureType: electronic
signature: John Hancock
responses:
'200':
description: OK
'403':
description: Forbidden
'404':
description: The case was not found.
'422':
description: The case doesn't include the e-Signature service, or the candidate already acknowledged
it.
'500':
description: Internal Server Error
get:
tags:
- Candidate onboarding
summary: Get E-Signature
description: 'Retrieves an e-Signature consent document and form that can be presented to and acknowledged
by the candidate as part of the onboarding process. If the candidate has already acknowledged
it, the response will indicate this as well as provide the `caseDataId` of the acknowledgement,
which can be used to retrieve details. These can be used to determine whether the candidate can
skip this step if they leave and then continue their onboarding later or on another device, for
example.
The e-Signature document can be customized. If a customer-specific version doesn''t exist, a default
one will be returned.'
operationId: get-case-id-caseId-esig-language
parameters:
- name: language
in: path
required: true
schema:
type: string
description: The language code (e.g. en-US)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- alreadyAck
- title
- body
- authorizationStatement
- authorizationObject
properties:
alreadyAck:
type: boolean
description: True if the candidate already acknowledged the e-Signature document;
false otherwise.
title:
type: string
description: Escaped HTML.
header:
type: string
description: Escaped HTML.
body:
type: string
description: Escaped HTML.
authorizationStatement:
type: string
description: Escaped HTML.
authorizationObject:
type: object
required:
- sections
properties:
header:
type: string
selectionType:
enum:
- single
- multi
sections:
type: array
items:
type: object
required:
- selectionValue
properties:
title:
type: string
selectionValue:
type: string
description: The value used when [acknowledging the e-Signature](karma-api-openapi.yaml/paths/~1case~1id~1{caseId}~1esig~1{language}/post).
enum:
- electronic
- manual
body:
type: string
caseDataId:
type: string
description: Returned only if `alreadyAck` is true
# --- truncated at 32 KB (486 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/karmacheck/refs/heads/main/openapi/karmacheck-api-openapi.yml