Skip to content

chore: sync v3 specs from lambda v3.549.0 #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Ed Fricker (beastawakens) merged 3 commits into from
May 8, 2026
Merged

chore: sync v3 specs from lambda v3.549.0 #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7c2fd00
chore: sync v3 specs from lambda v3.549.0
github-actions[bot] May 8, 2026
987c60a
Merge branch 'main' into sync/v3.549.0
beastawakens May 8, 2026
4ac8c63
Merge branch 'main' into sync/v3.549.0
beastawakens May 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,24 @@ All notable changes to the Smile Identity API specifications will be documented
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [Unreleased]
## [v3.549.0] - 2026-05-08

### Changed
- Updated `v3-biometric-authentication-entry`
- Updated `v3-biometric-enrollment-entry`
Comment on lines 7 to +12
- Updated `v3-biometric-kyc-entry`
- Updated `v3-block-user`
- Updated `v3-document-verification-entry`
- Updated `v3-enhanced-document-verification-entry`
- Updated `v3-enhanced-kyc-entry`
- Updated `v3-enhanced-kyc-job-status`
- Updated `v3-id-status`
- Updated `v3-replay-callback`
- Updated `v3-services`
- Updated `v3-smart-selfie-compare-entry`
- Updated `v3-supported-documents`
- Updated `v3-token`


### Added

Expand Down
280 changes: 280 additions & 0 deletions specs/v3/v3-biometric-authentication-entry.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,280 @@
openapi: 3.0.0

Check warning on line 1 in specs/v3/v3-biometric-authentication-entry.yaml

View workflow job for this annotation

GitHub Actions / validate 

oas3-api-servers
info:

Check warning on line 2 in specs/v3/v3-biometric-authentication-entry.yaml

View workflow job for this annotation

GitHub Actions / validate 

info-contact      Info object must have "contact" object.
title: V3 Biometric Authentication API
version: '1.0.0'
description: >-
Async biometric authentication endpoint (Smart Selfie™ Authentication).
Accepts a selfie image and liveness images, validates at entry, and queues the job
for async processing. The selfie is compared against the user's previously enrolled image.
Returns HTTP 202 with a job_id and user_id to track the result via callback.

Authentication: token-based (token header from /v3/token).

At least one of `email` or `phone_number` is required. The `user_id` field is required
and must match an existing enrolled user.
paths:
/v3/authenticate:
post:

Check warning on line 17 in specs/v3/v3-biometric-authentication-entry.yaml

View workflow job for this annotation

GitHub Actions / validate 

operation-tags    Operation must have non-empty "tags" array.
summary: Submit biometric authentication
operationId: v3BiometricAuthentication
description: >-
Authenticates a user by comparing a submitted selfie against their enrolled image.
The selfie and liveness images are uploaded, validated at entry, then queued for
async ML processing (passive liveness, active liveness, face matching).
Results are delivered via callback URL.

Supports `use_enrolled_image: true` to skip selfie/liveness upload and re-use the
enrolled image for the comparison (useful for server-side re-verification).
parameters:
- name: SmileID-Token
in: header
required: true
description: JWT token from /v3/token.
schema:
type: string
- name: SmileID-Source-SDK
in: header
required: false
description: Source SDK identifier.
schema:
type: string
example: 'android'
- name: SmileID-Source-SDK-Version
in: header
required: false
description: Source SDK version.
schema:
type: string
example: '10.4.2'
- name: SmileID-Timestamp
in: header
required: false
description: >-
ISO 8601 timestamp used as the salt when computing SmileID-Request-Signature.
schema:
type: string
format: date-time
- name: SmileID-Request-Signature
in: header
required: false
description: >-
HMAC signature of the raw HTTP request body.
schema:
type: string
- name: User-ID
in: header
required: false
description: >-
Partner-provided user identifier override.
schema:
type: string
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/BiometricAuthenticationRequest'
encoding:
selfie_image:
contentType: image/jpeg
liveness_images:
contentType: image/jpeg
responses:
'202':
description: Accepted — job queued for async processing.
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptedResponse'
example:
status: Accepted
message: Request accepted and queued for processing.
job_id: job_01h8x9y2z3a4b5c6d7e8f9g0h1
user_id: user_auth_001
created_at: '2026-03-10T12:00:00.000Z'
'400':
description: Bad Request — validation error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingUserId:
summary: Missing user_id
value:
status: Bad Request
message: "Required field 'user_id' is missing or invalid."
missingContact:
summary: Missing email and phone
value:
status: Bad Request
message: Either email or phone_number is required.
'401':
description: Unauthorized — invalid or missing authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'402':
description: Payment Required — insufficient wallet balance.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden — partner not authorized for this product or IP.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'415':
description: Unsupported Media Type — request must be multipart/form-data.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too Many Requests — rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'

components:
schemas:
BiometricAuthenticationRequest:
type: object
required:
- user_id
- consent
- user_details
properties:
user_id:
type: string
description: >-
The enrolled user's identifier. Must match an existing enrollee.
example: user_auth_001
selfie_image:
type: string
format: binary
description: >-
JPEG selfie image for authentication. Required unless use_enrolled_image is true.
liveness_images:
type: array
minItems: 6
maxItems: 8
items:
type: string
format: binary
description: >-
Array of 6–8 JPEG liveness images. Required unless use_enrolled_image is true.
consent:
$ref: '#/components/schemas/Consent'
user_details:
type: object
required:
- given_names
- last_name
description: >-
Consumer-stated PII fields for the user.
Either email or phone_number must be provided.
properties:
given_names:
type: string
minLength: 1
example: Jane
last_name:
type: string
minLength: 1
example: Smith
email:
type: string
format: email
nullable: true
description: At least one of email or phone_number is required.
example: jane@example.com
phone_number:
type: string
pattern: '^\+'
nullable: true
description: Phone number in E.164 format. At least one of email or phone_number is required.
example: '+2348012345678'
use_enrolled_image:
type: boolean
default: false
description: >-
If true, skips selfie and liveness image upload and uses the enrolled image
for re-verification. Useful for server-side re-authentication.
callback_url:
type: string
format: uri
description: URL to receive the async result callback.
example: https://example.com/callback
sandbox_result:
type: number
description: Force a specific result code in sandbox mode.
partner_params:
type: object
additionalProperties:
type: string
metadata:
type: array
items:
type: object
required: [name, value]
properties:
name:
type: string
maxLength: 100
value:
type: string
maxLength: 1000

Consent:
type: object
required: [granted, granted_at, notice_language, notice_privacy_policy_url]
properties:
granted:
type: boolean
enum: [true]
granted_at:
type: string
format: date-time
notice_language:
type: string
minLength: 2
maxLength: 2
pattern: '^[A-Z]{2}$'
notice_privacy_policy_url:
type: string
format: uri

AcceptedResponse:
type: object
properties:
status:
type: string
enum: [Accepted]
Comment on lines +258 to +263
Copy link
Copy Markdown

@prfectionist prfectionist Bot May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: The AcceptedResponse status enum uses Accepted (capitalized) here, but other new specs like v3-biometric-kyc-entry.yaml and v3-document-verification-entry.yaml use accepted (lowercase). This inconsistency will cause SDK code generation issues and client-side parsing failures when consumers check the status field across different endpoints. [general, importance: 6]

Suggested change
AcceptedResponse:
type: object
properties:
status:
type: string
enum: [Accepted]
AcceptedResponse:
type: object
properties:
status:
type: string
enum: [accepted]

message:
type: string
job_id:
type: string
user_id:
type: string
created_at:
type: string
format: date-time

ErrorResponse:
type: object
properties:
status:
type: string
message:
type: string
Loading
Loading