diff --git a/CHANGELOG.md b/CHANGELOG.md index a603b63..e3a6d5f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,17 @@ 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.553.0] - 2026-05-08 + +### Changed +- Updated `v3-services` +- Updated `v3-verification-status` + +### Removed +- `v3-enhanced-kyc-job-status` +- `v3-id-status` +- `v3-supported-documents` + ## [v3.549.0] - 2026-05-08 ### Changed diff --git a/README.md b/README.md index 629a204..082675e 100644 --- a/README.md +++ b/README.md @@ -14,14 +14,14 @@ OpenAPI 3.0 specifications for the Smile Identity v3 API. | [Document Verification](specs/v3/v3-document-verification-entry.yaml) | `POST /v3/document-verification` | Submit Document Verification | | [Enhanced Document Verification](specs/v3/v3-enhanced-document-verification-entry.yaml) | `POST /v3/enhanced-document-verification` | Submit Enhanced Document Verification | | [Enhanced KYC](specs/v3/v3-enhanced-kyc-entry.yaml) | `POST /v3/enhanced_kyc` | Submit Enhanced KYC verification | -| [Enhanced KYC Job Status](specs/v3/v3-enhanced-kyc-job-status.yaml) | `GET /v3/status/{jobId}` | Get verification status | -| [ID Status](specs/v3/v3-id-status.yaml) | `GET /v3/services/id_status` | Get ID type availability status | | [Replay Callback](specs/v3/v3-replay-callback.yaml) | `POST /v3/replay/{job_id}` | Replay a callback for a completed verification | | [Services](specs/v3/v3-services.yaml) | `GET /v3/services/bank_codes` | List bank codes | +| [Services](specs/v3/v3-services.yaml) | `GET /v3/services/id_status` | Get ID type availability status | +| [Services](specs/v3/v3-services.yaml) | `GET /v3/services/supported_documents` | List supported documents for verification | | [Services](specs/v3/v3-services.yaml) | `GET /v3/services/supported_id_types` | List supported KYC ID types | | [Smart Selfie Compare](specs/v3/v3-smart-selfie-compare-entry.yaml) | `POST /v3/smart_selfie_compare` | Submit smart selfie compare | -| [Supported Documents](specs/v3/v3-supported-documents.yaml) | `GET /v3/services/supported_documents` | List supported documents for verification | | [Token](specs/v3/v3-token.yaml) | `POST /v3/token` | Generate v3 Auth Token | +| [Verification Status](specs/v3/v3-verification-status.yaml) | `GET /v3/status/{jobId}` | Get verification status | > The table above is regenerated automatically on each spec sync. Don't hand-edit between the markers. diff --git a/docs/index.html b/docs/index.html index b2cc6d5..677cc2a 100644 --- a/docs/index.html +++ b/docs/index.html @@ -202,13 +202,11 @@

APIs

{ file: "v3-document-verification-entry", label: "Document Verification" }, { file: "v3-enhanced-document-verification-entry", label: "Enhanced Document Verification" }, { file: "v3-enhanced-kyc-entry", label: "Enhanced KYC" }, - { file: "v3-enhanced-kyc-job-status", label: "Enhanced KYC Job Status" }, - { file: "v3-id-status", label: "ID Status" }, { file: "v3-replay-callback", label: "Replay Callback" }, { file: "v3-services", label: "Services" }, { file: "v3-smart-selfie-compare-entry", label: "Smart Selfie Compare" }, - { file: "v3-supported-documents", label: "Supported Documents" }, - { file: "v3-token", label: "Token" } + { file: "v3-token", label: "Token" }, + { file: "v3-verification-status", label: "Verification Status" } ]; // diff --git a/specs/v3/v3-id-status.yaml b/specs/v3/v3-id-status.yaml deleted file mode 100644 index c34f3af..0000000 --- a/specs/v3/v3-id-status.yaml +++ /dev/null @@ -1,140 +0,0 @@ -openapi: 3.0.3 -info: - title: Smile ID – ID Status API - description: | - Returns the current availability status of a given ID type for a country. - - **Authentication**: Only JWT token auth is supported. Pass the token - obtained from `POST /v3/token` in the `SmileID-Token` header. - Signature-based auth (`smileid-request-signature` / `smileid-timestamp`) - is not accepted. - version: 3.0.0 - -paths: - /v3/services/id_status: - get: - operationId: getIdStatus - summary: Get ID type availability status - description: | - Returns the current availability and success rate for a specific ID type - in a given country, based on uptime data from the last hour. - - Requires authentication via JWT token. - tags: - - Services - security: - - SmileIDToken: [] - parameters: - - name: country - in: query - required: true - description: ISO 3166-1 alpha-2 country code or full country name (e.g. "NG" or "Nigeria"). - schema: - type: string - example: NG - - name: id_type - in: query - required: true - description: The ID type code to check status for (e.g. "BVN", "NIN", "VOTER_ID"). - schema: - type: string - example: BVN - responses: - '200': - description: ID status retrieved successfully. - content: - application/json: - schema: - type: object - required: - - last_checked - - last_check_status - - last_hour_success_rate - - last_known_status - - last_check_success_rate - properties: - last_checked: - type: string - format: date-time - description: Timestamp of the most recent uptime check. - example: '2026-04-14T12:30:00.000Z' - last_check_status: - type: string - enum: [success, failure] - description: Whether the most recent check succeeded or failed. - example: success - last_hour_success_rate: - type: string - description: Aggregate success rate over the last hour as a percentage. - example: '95%' - last_known_status: - type: string - description: The raw status string from the most recent check (e.g. "online", "offline"). - example: online - last_check_success_rate: - type: string - description: Success rate of the most recent individual check as a percentage. - example: '90%' - example: - last_checked: '2026-04-14T12:30:00.000Z' - last_check_status: success - last_hour_success_rate: '95%' - last_known_status: online - last_check_success_rate: '90%' - '400': - description: Bad request – missing or invalid parameters, or no uptime data found. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse' - examples: - missingCountry: - summary: Country parameter missing - value: - message: '"country" is required' - status: Bad Request - invalidCountry: - summary: Invalid country value - value: - message: Invalid country - status: Bad Request - invalidIdType: - summary: ID type not valid for country - value: - message: Invalid id_type for the given country - status: Bad Request - noData: - summary: No uptime data in the last hour - value: - message: 'No data found. Check that NG and BVN are valid inputs' - status: Bad Request - '401': - description: Authentication failed. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse' - example: - message: Invalid token - status: Unauthorized - -components: - securitySchemes: - SmileIDToken: - type: apiKey - in: header - name: SmileID-Token - description: JWT token obtained from `POST /v3/token`. - schemas: - ErrorResponse: - type: object - required: - - message - - status - properties: - message: - type: string - description: Human-readable error message. - status: - type: string - description: HTTP status text (e.g. "Bad Request", "Unauthorized"). diff --git a/specs/v3/v3-services.yaml b/specs/v3/v3-services.yaml index 092c506..3b1b26d 100644 --- a/specs/v3/v3-services.yaml +++ b/specs/v3/v3-services.yaml @@ -3,11 +3,11 @@ info: title: V3 Services API version: 1.0.0 description: | - Read-only reference endpoints that return static configuration data: supported bank - codes and KYC ID types. Both endpoints accept an optional `country` query parameter - to filter results by ISO 3166-1 alpha-2 country code. + Reference endpoints that return configuration and status data: bank codes, supported ID types, + supported documents, and ID type availability status. - These endpoints do not require authentication. + Most endpoints do not require authentication. The `GET /v3/services/id_status` endpoint + requires a JWT token passed in the `SmileID-Token` header. servers: - url: https://api.smileidentity.com @@ -31,6 +31,13 @@ components: pattern: '^[A-Z]{2}$' example: NG + securitySchemes: + SmileIDToken: + type: apiKey + in: header + name: SmileID-Token + description: JWT token obtained from `POST /v3/token`. + schemas: BankCode: type: object @@ -112,6 +119,95 @@ components: items: $ref: '#/components/schemas/SupportedIdType' + Country: + type: object + properties: + code: + type: string + description: ISO 3166-1 alpha-2 country code. + example: NG + name: + type: string + description: Country name. + example: Nigeria + continent: + type: string + description: Continent name. + example: AFRICA + + IDType: + type: object + properties: + code: + type: string + description: Machine-readable ID type code. + example: DRIVERS_LICENSE + name: + type: string + description: Human-readable name of the ID type. + example: Driver's License + example: + type: array + items: + type: string + description: Example ID numbers or usage hints. + has_back: + type: boolean + description: Whether this document type has a back side that should be captured. + example: true + + SupportedDocument: + type: object + properties: + country: + $ref: '#/components/schemas/Country' + id_types: + type: array + items: + $ref: '#/components/schemas/IDType' + + SupportedDocumentsResponse: + type: object + required: + - valid_documents + properties: + valid_documents: + type: array + items: + $ref: '#/components/schemas/SupportedDocument' + + IdStatusResponse: + type: object + required: + - last_checked + - last_check_status + - last_hour_success_rate + - last_known_status + - last_check_success_rate + properties: + last_checked: + type: string + format: date-time + description: Timestamp of the most recent uptime check. + example: '2026-04-14T12:30:00.000Z' + last_check_status: + type: string + enum: [success, failure] + description: Whether the most recent check succeeded or failed. + example: success + last_hour_success_rate: + type: string + description: Aggregate success rate over the last hour as a percentage. + example: '95%' + last_known_status: + type: string + description: The raw status string from the most recent check (e.g. "online", "offline"). + example: online + last_check_success_rate: + type: string + description: Success rate of the most recent individual check as a percentage. + example: '90%' + ErrorResponse: type: object properties: @@ -122,6 +218,19 @@ components: type: string description: Smile Identity error code. + IdStatusErrorResponse: + type: object + required: + - message + - status + properties: + message: + type: string + description: Human-readable error message. + status: + type: string + description: HTTP status text (e.g. "Bad Request", "Unauthorized"). + paths: /v3/services/bank_codes: get: @@ -203,3 +312,174 @@ paths: example: error: You are not authorized to do that. code: '2413' + + /v3/services/supported_documents: + get: + operationId: getSupportedDocuments + summary: List supported documents for verification + description: | + Returns a list of supported document types for identity verification across all + countries served by Smile Identity. + + The response can be filtered by continent or country code. An optional `locale` + parameter controls the language of document names. + + This endpoint does not require authentication. It is an alias of + `GET /v1/valid_documents` and `GET /v3/valid-documents`. + security: [] + parameters: + - name: continent + in: query + required: false + description: Filter results to a single continent. + schema: + type: string + enum: + - AFRICA + - ASIA + - EUROPE + - 'NORTH AMERICA' + - OCEANIA + - 'SOUTH AMERICA' + example: AFRICA + - name: country_code + in: query + required: false + description: | + Filter results to a single country. Must be an ISO 3166-1 alpha-2 code + (two uppercase letters). + schema: + type: string + pattern: '^[A-Z]{2}$' + example: NG + - name: locale + in: query + required: false + description: | + Locale for document names. Defaults to `en-GB`. + Supported values: `en-GB`, `fr-FR`, `ar-EG`. + schema: + type: string + default: en-GB + enum: + - en-GB + - fr-FR + - ar-EG + responses: + '200': + description: List of supported documents, optionally filtered. + content: + application/json: + schema: + $ref: '#/components/schemas/SupportedDocumentsResponse' + example: + valid_documents: + - country: + code: NG + name: Nigeria + continent: AFRICA + id_types: + - code: DRIVERS_LICENSE + name: Driver's License + example: ['AAA00000AA00'] + has_back: true + - code: NATIONAL_ID + name: National ID (NIN Slip) + example: ['00000000000'] + has_back: false + '400': + description: Invalid query parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + error: >- + Country Code must be a valid ISO 3166-1 alpha-2 country code + consisting of exactly two uppercase letters. + code: '2413' + '500': + description: Internal server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + error: System Error + code: '2401' + + /v3/services/id_status: + get: + operationId: getIdStatus + summary: Get ID type availability status + description: | + Returns the current availability and success rate for a specific ID type + in a given country, based on uptime data from the last hour. + + Requires authentication via JWT token. + security: + - SmileIDToken: [] + parameters: + - name: country + in: query + required: true + description: ISO 3166-1 alpha-2 country code or full country name (e.g. "NG" or "Nigeria"). + schema: + type: string + example: NG + - name: id_type + in: query + required: true + description: The ID type code to check status for (e.g. "BVN", "NIN", "VOTER_ID"). + schema: + type: string + example: BVN + responses: + '200': + description: ID status retrieved successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/IdStatusResponse' + example: + last_checked: '2026-04-14T12:30:00.000Z' + last_check_status: success + last_hour_success_rate: '95%' + last_known_status: online + last_check_success_rate: '90%' + '400': + description: Bad request – missing or invalid parameters, or no uptime data found. + content: + application/json: + schema: + $ref: '#/components/schemas/IdStatusErrorResponse' + examples: + missingCountry: + summary: Country parameter missing + value: + message: '"country" is required' + status: Bad Request + invalidCountry: + summary: Invalid country value + value: + message: Invalid country + status: Bad Request + invalidIdType: + summary: ID type not valid for country + value: + message: Invalid id_type for the given country + status: Bad Request + noData: + summary: No uptime data in the last hour + value: + message: 'No data found. Check that NG and BVN are valid inputs' + status: Bad Request + '401': + description: Authentication failed. + content: + application/json: + schema: + $ref: '#/components/schemas/IdStatusErrorResponse' + example: + message: Invalid token + status: Unauthorized diff --git a/specs/v3/v3-supported-documents.yaml b/specs/v3/v3-supported-documents.yaml deleted file mode 100644 index 35946c4..0000000 --- a/specs/v3/v3-supported-documents.yaml +++ /dev/null @@ -1,187 +0,0 @@ -openapi: 3.0.3 -info: - title: V3 Supported Documents API - version: 1.0.0 - description: | - Retrieves a list of supported document types for identity verification, filterable by - continent, country code, or locale. - - This endpoint does not require authentication. - - This endpoint is an alias of `GET /v1/valid_documents` and `GET /v3/valid-documents`, - providing the same data under a more descriptive path. - -servers: - - url: https://api.smileidentity.com - description: Production - - url: https://testapi.smileidentity.com - description: Sandbox - - url: https://devapi.smileidentity.com - description: Development - -components: - schemas: - Country: - type: object - properties: - code: - type: string - description: ISO 3166-1 alpha-2 country code. - example: NG - name: - type: string - description: Country name. - example: Nigeria - continent: - type: string - description: Continent name. - example: AFRICA - - IDType: - type: object - properties: - code: - type: string - description: Machine-readable ID type code. - example: DRIVERS_LICENSE - name: - type: string - description: Human-readable name of the ID type. - example: Driver's License - example: - type: array - items: - type: string - description: Example ID numbers or usage hints. - has_back: - type: boolean - description: Whether this document type has a back side that should be captured. - example: true - - SupportedDocument: - type: object - properties: - country: - $ref: '#/components/schemas/Country' - id_types: - type: array - items: - $ref: '#/components/schemas/IDType' - - SupportedDocumentsResponse: - type: object - properties: - valid_documents: - type: array - items: - $ref: '#/components/schemas/SupportedDocument' - required: - - valid_documents - - ErrorResponse: - type: object - properties: - error: - type: string - description: Human-readable error message. - code: - type: string - description: Smile Identity error code. - required: - - error - - code - -paths: - /v3/services/supported_documents: - get: - summary: List supported documents for verification - operationId: getSupportedDocuments - description: | - Returns a list of supported document types for identity verification across all - countries served by Smile Identity. - - The response can be filtered by continent or country code. An optional `locale` - parameter controls the language of document names. - tags: - - Services - security: [] - parameters: - - name: continent - in: query - required: false - description: Filter results to a single continent. - schema: - type: string - enum: - - AFRICA - - ASIA - - EUROPE - - 'NORTH AMERICA' - - OCEANIA - - 'SOUTH AMERICA' - example: AFRICA - - name: country_code - in: query - required: false - description: | - Filter results to a single country. Must be an ISO 3166-1 alpha-2 code - (two uppercase letters). - schema: - type: string - pattern: '^[A-Z]{2}$' - example: NG - - name: locale - in: query - required: false - description: | - Locale for document names. Defaults to `en-GB`. - Supported values: `en-GB`, `fr-FR`, `ar-EG`. - schema: - type: string - default: en-GB - enum: - - en-GB - - fr-FR - - ar-EG - responses: - '200': - description: List of supported documents, optionally filtered. - content: - application/json: - schema: - $ref: '#/components/schemas/SupportedDocumentsResponse' - example: - valid_documents: - - country: - code: NG - name: Nigeria - continent: AFRICA - id_types: - - code: DRIVERS_LICENSE - name: Driver's License - example: ['AAA00000AA00'] - has_back: true - - code: NATIONAL_ID - name: National ID (NIN Slip) - example: ['00000000000'] - has_back: false - '400': - description: Invalid query parameters. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse' - example: - error: >- - Country Code must be a valid ISO 3166-1 alpha-2 country code - consisting of exactly two uppercase letters. - code: '2413' - '500': - description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse' - example: - error: System Error - code: '2401' diff --git a/specs/v3/v3-enhanced-kyc-job-status.yaml b/specs/v3/v3-verification-status.yaml similarity index 99% rename from specs/v3/v3-enhanced-kyc-job-status.yaml rename to specs/v3/v3-verification-status.yaml index 4d4f309..5e9e26f 100644 --- a/specs/v3/v3-enhanced-kyc-job-status.yaml +++ b/specs/v3/v3-verification-status.yaml @@ -13,7 +13,7 @@ info: paths: /v3/status/{jobId}: get: - operationId: getEnhancedKycJobStatus + operationId: getVerificationStatus summary: Get verification status description: >- Retrieves the current status of a previously submitted verification.