openapi: 3.0.3 info: title: Certn API description: >- Certn is a background check and identity verification platform. This API lets partner platforms (HR, property management, gig/marketplace) order background screening for applicants, retrieve consolidated reports, manage the checks and packages that make up a screen, and receive status updates via signed webhooks. Certn screens candidates across 200+ countries and territories. Authentication uses OAuth 2.0 client credentials: a Client ID and Client Secret (created in the Partner tab under API Keys) are exchanged for a Bearer access token that is sent on every request. Base URL is https://api.certn.co for production and https://demo-api.certn.co for the demo/testing environment. IMPORTANT - endpoint provenance: The original api.certn.co v1 REST endpoints (under /api/v1/hr, /api/v1/pm, /api/v1/users, /api/v2/teams) are documented and CONFIRMED against the public reference, but Certn deprecated them on 2026-04-13 with discontinuation on 2026-08-05 in favor of the newer CertnCentric APIs. The CertnCentric documentation portal (centric-api-docs.certn.co) is a client-rendered SPA whose exact endpoint paths could not be scraped; its resource groupings (cases, checks, reports, packages, webhooks) are MODELED here honestly and marked with x-endpoint-status. Confirm all shapes against the live docs before use. version: '1.0' contact: name: Certn url: https://certn.co license: name: Proprietary url: https://certn.co/terms/ servers: - url: https://api.certn.co description: Production - url: https://demo-api.certn.co description: Demo / testing security: - bearerAuth: [] tags: - name: Applications description: Invite or instantly screen applicants and list applications (HR and PM surfaces). - name: Checks description: Individual check types requested and returned within an application. - name: Reports description: Consolidated applicant screening reports and results. - name: Packages description: Predefined bundles of checks and application upgrades. - name: Webhooks description: Signed server-to-server callbacks for screening status updates. - name: Teams and Users description: Organizational hierarchy - Superteams, Teams, Users, reference templates. paths: /api/v1/hr/applications/invite/: post: operationId: inviteHrApplicant tags: - Applications summary: Invite an HR applicant to complete a screen description: >- Invite an applicant to complete a screen via email. The applicant fills in their own information and consent, then the requested checks run. (Deprecated in the v1 API; use the CertnCentric equivalent.) deprecated: true x-endpoint-status: confirmed requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ApplicationInvite' responses: '201': description: Application created and invitation sent. content: application/json: schema: $ref: '#/components/schemas/Application' '401': $ref: '#/components/responses/Unauthorized' /api/v1/hr/applications/quick/: post: operationId: quickScreenHrApplicant tags: - Applications summary: Screen an HR applicant instantly description: >- Screen an applicant using only the information supplied in the body of the request, without sending an invitation email. (Deprecated in the v1 API.) deprecated: true x-endpoint-status: confirmed requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QuickScreen' responses: '201': description: Application created and screening started. content: application/json: schema: $ref: '#/components/schemas/Application' '401': $ref: '#/components/responses/Unauthorized' /api/v1/hr/applicants/: get: operationId: listHrApplicants tags: - Applications summary: List HR applications description: >- Retrieve a paginated list of all applications, in chronological order, with filtering by team or owner. x-endpoint-status: confirmed parameters: - $ref: '#/components/parameters/Team' - $ref: '#/components/parameters/Owner' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' responses: '200': description: A paginated list of applications. content: application/json: schema: $ref: '#/components/schemas/ApplicationList' '401': $ref: '#/components/responses/Unauthorized' /api/v1/hr/applicants/{applicant_id}/packages/: put: operationId: upgradeHrApplication tags: - Packages summary: Add screening requests to an existing application description: >- Upgrade an application by adding further screening requests (checks or a package) to an existing applicant after the initial report returns. (Deprecated in the v1 API.) deprecated: true x-endpoint-status: confirmed parameters: - $ref: '#/components/parameters/ApplicantId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PackageUpgrade' responses: '200': description: Application upgraded with the added requests. content: application/json: schema: $ref: '#/components/schemas/Application' '401': $ref: '#/components/responses/Unauthorized' /api/v1/pm/applications/invite/: post: operationId: invitePmApplicant tags: - Applications summary: Invite a property-management applicant to complete a screen description: >- Invite one or more applicants to complete a property-management screening form; supports batch invitations. (Deprecated in the v1 API.) deprecated: true x-endpoint-status: confirmed requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ApplicationInvite' responses: '201': description: Application(s) created and invitation(s) sent. content: application/json: schema: $ref: '#/components/schemas/Application' '401': $ref: '#/components/responses/Unauthorized' /api/v1/pm/applications/quick/: post: operationId: quickScreenPmApplicant tags: - Applications summary: Screen a property-management applicant instantly description: >- Screen an applicant using only the information in the body of the request. (Deprecated in the v1 API.) deprecated: true x-endpoint-status: confirmed requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QuickScreen' responses: '201': description: Application created and screening started. content: application/json: schema: $ref: '#/components/schemas/Application' '401': $ref: '#/components/responses/Unauthorized' /api/v1/pm/applicants/: get: operationId: listPmApplicants tags: - Applications summary: List property-management applications description: View details of all applications, paginated in chronological order. x-endpoint-status: confirmed parameters: - $ref: '#/components/parameters/Team' - $ref: '#/components/parameters/Owner' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' responses: '200': description: A paginated list of applications. content: application/json: schema: $ref: '#/components/schemas/ApplicationList' '401': $ref: '#/components/responses/Unauthorized' /api/v1/reports/{applicant_id}/: get: operationId: getApplicantReport tags: - Reports summary: Retrieve an applicant's consolidated report description: >- Retrieve the consolidated screening report for an applicant, including each requested check's status and findings, verified identity and financial data, and an overall risk assessment. MODELED: the report payload is returned within the applicant object on the confirmed v1 list endpoints; this dedicated path mirrors the CertnCentric reports resource and should be confirmed against the live docs. x-endpoint-status: modeled parameters: - $ref: '#/components/parameters/ApplicantId' responses: '200': description: The applicant's consolidated report. content: application/json: schema: $ref: '#/components/schemas/Report' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /api/v1/checks/: get: operationId: listAvailableChecks tags: - Checks summary: List available check types description: >- List the check types available to the account (criminal, identity/OneID, credit, public records, employment, education, credential, professional reference, driver's abstract, working-with-children, social media, and international variants). MODELED from the published check catalog; confirm the exact path and schema against the CertnCentric docs. x-endpoint-status: modeled responses: '200': description: A list of available check types. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Check' '401': $ref: '#/components/responses/Unauthorized' /api/v1/packages/: get: operationId: listPackages tags: - Packages summary: List screening packages description: >- List the predefined screening packages configured for the account or team (for example the CertnCentric Essential, Pro, and Elite tiers), each a named bundle of checks. MODELED from the general-resources docs; confirm the exact path against the CertnCentric docs. x-endpoint-status: modeled parameters: - $ref: '#/components/parameters/Team' responses: '200': description: A list of packages. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Package' '401': $ref: '#/components/responses/Unauthorized' /api/v1/users/: get: operationId: listUsers tags: - Teams and Users summary: List users in the account description: >- Retrieve a list of users in your organizational account. Each user is returned with a UUID id and profile fields. x-endpoint-status: confirmed responses: '200': description: A list of users. content: application/json: schema: type: object properties: results: type: array items: $ref: '#/components/schemas/User' '401': $ref: '#/components/responses/Unauthorized' /api/v2/teams/: get: operationId: listTeams tags: - Teams and Users summary: Retrieve all teams description: >- Retrieve all teams in the account. Superteams contain Teams which contain Users. (Deprecated in the v1/v2 API.) deprecated: true x-endpoint-status: confirmed responses: '200': description: A list of teams. content: application/json: schema: type: object properties: results: type: array items: $ref: '#/components/schemas/Team' '401': $ref: '#/components/responses/Unauthorized' /api/v2/teams/{team_id}/address/reference_templates/: get: operationId: getAddressReferenceTemplates tags: - Teams and Users summary: Retrieve address reference templates description: >- Retrieve the templated address-reference questionnaires configured for a team, including question types (TRUE_FALSE, MULTIPLE_CHOICE, NUMERIC_RANGE, LONG_ANSWER) and variable substitution. (Deprecated in the v2 API.) deprecated: true x-endpoint-status: confirmed parameters: - $ref: '#/components/parameters/TeamId' responses: '200': description: A list of address reference templates. content: application/json: schema: type: object properties: results: type: array items: $ref: '#/components/schemas/ReferenceTemplate' '401': $ref: '#/components/responses/Unauthorized' /webhooks/receiver: post: operationId: receiveWebhook tags: - Webhooks summary: Webhook receiver (implemented on your side) description: >- Documentation of the callback contract. Certn POSTs screening status updates to the endpoint URL you register in the Partner dashboard as results become available. Each request carries a Certn-Signature header (an HMAC-SHA256 over "{timestamp}.{json_body}" with a t= timestamp and a v1= signature) so you can verify authenticity and guard against replay. Certn retries up to three additional times on 408/500/502/503/504. There is no public REST endpoint to register webhooks - configuration is done in the Partner dashboard. This path documents the payload you receive, not a Certn-hosted endpoint. x-endpoint-status: modeled parameters: - name: Certn-Signature in: header required: true description: HMAC-SHA256 signature "t={timestamp},v1={signature}". schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEvent' responses: '200': description: Acknowledge receipt (your endpoint should return 2xx). components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- OAuth 2.0 client credentials. Exchange your Client ID and Client Secret for an access token, then send it as "Authorization: Bearer {token}". parameters: ApplicantId: name: applicant_id in: path required: true description: The UUID of the applicant / application. schema: type: string format: uuid TeamId: name: team_id in: path required: true description: The UUID of the team. schema: type: string format: uuid Team: name: team in: query required: false description: Filter results by team ID. schema: type: string Owner: name: owner in: query required: false description: Filter results by owner (user) ID. schema: type: string Offset: name: offset in: query required: false description: Number of records to skip for pagination. schema: type: integer minimum: 0 Limit: name: limit in: query required: false description: Maximum number of records to return. schema: type: integer minimum: 1 maximum: 100 responses: Unauthorized: description: Missing or invalid Bearer token. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: ApplicationInvite: type: object description: Request to invite an applicant to complete a screen. required: - email properties: email: type: string format: email description: Applicant email to send the invitation to. first_name: type: string last_name: type: string package: type: string description: ID of the screening package to apply. team: type: string description: Team ID that owns the application. request_criminal_record_check: type: boolean request_identity_verification: type: boolean request_credit_check: type: boolean request_employment_verification: type: boolean request_education_verification: type: boolean request_reference_check: type: boolean QuickScreen: type: object description: Instant screen using information supplied directly in the request. required: - email properties: email: type: string format: email first_name: type: string last_name: type: string date_of_birth: type: string format: date package: type: string checks: type: array items: type: string description: Check type identifiers to run. PackageUpgrade: type: object description: Additional screening requests to add to an existing application. properties: package: type: string description: ID of a package to add. checks: type: array items: type: string description: Additional check type identifiers to add. Application: type: object description: A screening application for an applicant. properties: id: type: string format: uuid status: type: string description: Overall application status (e.g. PENDING, ANALYZING, COMPLETE). applicant: $ref: '#/components/schemas/Applicant' checks: type: array items: $ref: '#/components/schemas/Check' report: $ref: '#/components/schemas/Report' created: type: string format: date-time modified: type: string format: date-time ApplicationList: type: object properties: count: type: integer next: type: string nullable: true previous: type: string nullable: true results: type: array items: $ref: '#/components/schemas/Application' Applicant: type: object properties: id: type: string format: uuid first_name: type: string last_name: type: string email: type: string format: email date_of_birth: type: string format: date Check: type: object description: An individual check within an application, or an available check type. properties: id: type: string format: uuid type: type: string description: >- Check type - e.g. CRIMINAL_RECORD_CHECK, ENHANCED_CRIMINAL_RECORD_CHECK, INTERNATIONAL_CRIMINAL_RECORD_CHECK, IDENTITY_VERIFICATION, CREDIT_CHECK, PUBLIC_RECORDS, EMPLOYMENT_VERIFICATION, EDUCATION_VERIFICATION, CREDENTIAL_VERIFICATION, REFERENCE_CHECK, DRIVERS_ABSTRACT, WORKING_WITH_CHILDREN, SOCIAL_MEDIA. status: type: string description: Check status (e.g. PENDING, ANALYZING, COMPLETE, CANCELLED). result: type: string description: Adjudicated result (e.g. CLEAR, CONSIDER, IN_DISPUTE). country: type: string description: ISO country code the check was run in. Report: type: object description: Consolidated report across all checks in an application. properties: id: type: string format: uuid applicant_id: type: string format: uuid overall_result: type: string description: Overall adjudicated outcome / risk assessment. risk_assessment: type: string checks: type: array items: $ref: '#/components/schemas/Check' report_url: type: string format: uri description: Link to the rendered PDF/HTML report. completed: type: string format: date-time Package: type: object description: A named bundle of checks. properties: id: type: string format: uuid name: type: string checks: type: array items: type: string team: type: string User: type: object properties: id: type: string format: uuid email: type: string format: email first_name: type: string last_name: type: string Team: type: object properties: id: type: string format: uuid name: type: string superteam: type: string format: uuid ReferenceTemplate: type: object properties: id: type: string format: uuid name: type: string questions: type: array items: type: object properties: text: type: string type: type: string enum: - TRUE_FALSE - MULTIPLE_CHOICE - NUMERIC_RANGE - LONG_ANSWER required: type: boolean verifiable: type: boolean WebhookEvent: type: object description: Payload Certn POSTs to your registered webhook endpoint. properties: event: type: string description: Event type (e.g. application.updated, check.completed, report.completed). applicant_id: type: string format: uuid status: type: string timestamp: type: string format: date-time data: type: object description: The updated application / check / report object. Error: type: object properties: detail: type: string code: type: string