> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idmetagroup.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Signature Matching
> Compare two signature images and return a similarity score and match verdict through the passthrough endpoint.
The response includes a similarity score, the match verdict, and the verification status for the two submitted signatures.
## Request fields
### `image1`
The first signature image. For example, the reference signature you hold on file for the customer.
Required. Each image can be at most 2 MB after decoding.
### `image2`
The second signature image to compare against `image1`. For example, a newly captured signature.
Required. Accepts the same formats as `image1`.
### `metadata`
Optional client-provided correlation data, such as your own reference ID. The API returns this object unchanged in the response.
## Supported image formats
Send `application/json` with each image as a Base64-encoded string. The data URI prefix is optional.
| Format | Example value |
| - | - |
| Base64 string | `` |
| Data URI | `data:image/png;base64,` |
```json theme={null}
{
"image1": "",
"image2": ""
}
```
Send `multipart/form-data` with each image as a file. Send each `metadata` key as its own form field.
| Form field | Value |
| - | - |
| `image1` | First signature image file |
| `image2` | Second signature image file |
| `metadata[referenceId]` | Your reference ID (optional) |
```bash theme={null}
curl --request POST \
--url "https://{environment-subdomain}.idmetagroup.com/api/v3/verifications/signature-matching-passthrough" \
--header "Authorization: Bearer " \
--form "image1=@/path/to/signature-1.png" \
--form "image2=@/path/to/signature-2.png" \
--form "metadata[referenceId]=SIGNATURE-MATCH-0001"
```
## Example request
This request compares a PNG signature with a JPEG signature sent as data URIs, and attaches a reference ID and source for correlation.
```json theme={null}
{
"image1": "data:image/png;base64,",
"image2": "data:image/jpeg;base64,"
}
```
## Interpret the response
`success: true` means the API completed the comparison. Use `verificationStatus` and `data.verdict` to determine the outcome.
| Field | Meaning |
| - | - |
| `data.similarity` | Similarity score between the two signatures. Higher values indicate a closer match. |
| `data.verdict` | Match verdict: `MATCH`, `INCONCLUSIVE`, or `NO MATCH`. |
| `data.verdictDisplay` | Human-readable form of the verdict: `Match`, `Inconclusive`, or `No Match`. |
| `verificationStatus` | Verification outcome derived from the verdict. |
| `transactionId` | Identifier for this comparison. `null` when the request fails validation. |
| `metadata` | The `metadata` object you sent, returned unchanged. |
The verdict maps to the verification status as follows:
| `data.verdict` | `verificationStatus` | Code | HTTP | Billable |
| - | - | - | - | - |
| `MATCH` | `VERIFIED` | `3` | `200` | Yes |
| `NO MATCH` | `REJECTED` | `1` | `200` | Yes |
| `INCONCLUSIVE` | `REVIEW_NEEDED` | `2` | `200` | Yes |
| No valid result | `FAILED` | `6` | `400` | No |
| Provider failure | `FAILED` | `6` | `502` | No |
`REJECTED` and `REVIEW_NEEDED` are completed comparisons, not API failures. `FAILED` means the comparison could not be completed, either because no signature was found in one of the images (HTTP `400`) or because the verification provider is unavailable (HTTP `502`). A request missing `image1` or `image2` also returns HTTP `400`, before a transaction is created.
## OpenAPI
````yaml stateless-verification-api/compliance/signature-matching.openapi.json POST /api/v3/verifications/signature-matching-passthrough
openapi: 3.0.3
info:
title: Signature Matching Passthrough API
version: 1.0.0
servers:
- url: https://{environment-subdomain}.idmetagroup.com
description: Your environment (replace `{environment-subdomain}`)
variables:
environment-subdomain:
default: integrate
description: IDmeta environment subdomain
security:
- bearerAuth: []
paths:
/api/v3/verifications/signature-matching-passthrough:
post:
tags:
- Compliance Verification
summary: Signature Matching
description: >-
Compare two signature images and return a similarity score and match
verdict.
Send the two signatures to compare as `image1` and `image2`. Both are
required. Use `application/json` with Base64-encoded images (the data
URI prefix is optional), or `multipart/form-data` with image file
uploads. Each image can be at most 2 MB after decoding. Image URLs are
not accepted.
The verdict decides the outcome: `MATCH` → `VERIFIED`; `INCONCLUSIVE` →
`REVIEW_NEEDED`; `NO MATCH` → `REJECTED`. All three are completed
comparisons returned as HTTP 200, and all three are billed.
`verificationStatusCode`: `3` = Verified, `2` = Review Needed, `1` =
Rejected, `6` = Failed.
HTTP `400` and `502` mean the comparison could not be completed. These
responses are not billed.
operationId: signatureMatchingPassthrough
parameters:
- name: Authorization
in: header
required: true
schema:
type: string
example: Bearer {your_api_token}
- name: Accept
in: header
required: false
schema:
type: string
default: application/json
- name: Content-Type
in: header
required: false
schema:
type: string
default: application/json
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SignatureMatchingRequest'
examples:
base64:
summary: Base64-encoded images
value:
image1:
image2:
dataUri:
summary: Data URI images
value:
image1: data:image/png;base64,
image2: data:image/jpeg;base64,
multipart/form-data:
schema:
type: object
properties:
image1:
type: string
format: binary
description: First signature image file. Maximum 2 MB.
image2:
type: string
format: binary
description: Second signature image file. Maximum 2 MB.
required:
- image1
- image2
responses:
'200':
description: >-
Comparison completed. Verified, review-needed, and rejected outcomes
all use HTTP 200 and are billed.
content:
application/json:
schema:
$ref: '#/components/schemas/SignatureMatchingSuccessResponse'
examples:
verified:
summary: Signatures matched
value:
success: true
message: Signature Matching processed successfully
data:
similarity: 92.75
verdict: MATCH
verdictDisplay: Match
verificationStatus: VERIFIED
verificationStatusCode: 3
transactionId: 7636df44-e539-4876-a4d5-408884229a92
verificationType: signature_matching
createdAt: 2026-10-06 06:15:00+0000
reviewNeeded:
summary: Comparison was inconclusive
description: A completed and billable comparison.
value:
success: true
message: Signature Matching processed successfully
data:
similarity: 43
verdict: INCONCLUSIVE
verdictDisplay: Inconclusive
verificationStatus: REVIEW_NEEDED
verificationStatusCode: 2
transactionId: 488c4155-a538-4e98-a178-ea53c7a35326
verificationType: signature_matching
createdAt: 2026-10-06 06:12:38+0000
rejected:
summary: Signatures did not match (still HTTP 200)
description: A completed and billable comparison, not an API failure.
value:
success: true
message: Signature Matching processed successfully
data:
similarity: 18.25
verdict: NO MATCH
verdictDisplay: No Match
verificationStatus: REJECTED
verificationStatusCode: 1
transactionId: f84fbe33-a147-42e5-b710-fe1725291327
verificationType: signature_matching
createdAt: 2026-10-06 06:16:00+0000
'400':
description: >-
Validation failed, or a submitted signature could not be processed.
Nothing was compared and the call is not billed.
content:
application/json:
schema:
oneOf:
- $ref: >-
#/components/schemas/SignatureMatchingValidationErrorResponse
- $ref: '#/components/schemas/SignatureMatchingErrorResponse'
examples:
invalidRequest:
summary: Required fields are missing
description: >-
Validation runs before a transaction is created, so
`transactionId` is `null`.
value:
success: false
code: VALIDATION_FAILED
message: >-
The request could not be validated. Please check the
submitted fields.
errors:
image1:
- The image1 field is required.
image2:
- The image2 field is required.
transactionId: null
verificationType: signature_matching
createdAt: 2026-10-06 06:19:00+0000
noSignatureDetected:
summary: A submitted signature could not be processed
description: >-
The transaction was created, but nothing was compared. This
is a failure rather than a rejection, and it is not billed.
value:
success: false
code: VALIDATION_FAILED
message: No signature detected in image1
verificationStatus: FAILED
verificationStatusCode: 6
transactionId: df0e8591-8ca6-4669-a21b-da9c672fb365
verificationType: signature_matching
createdAt: 2026-10-06 06:18:00+0000
'502':
description: >-
The signature matching provider could not be reached. The call is
not billed.
content:
application/json:
schema:
$ref: '#/components/schemas/SignatureMatchingErrorResponse'
examples:
sourceUnavailable:
summary: Verification provider unavailable
value:
success: false
code: SOURCE_UNAVAILABLE
message: >-
The verification source is currently unavailable. Please
try again later.
verificationStatus: FAILED
verificationStatusCode: 6
transactionId: c53add1e-9ed6-4417-8df0-7fa7f1883c40
verificationType: signature_matching
createdAt: 2026-10-06 06:17:00+0000
components:
schemas:
SignatureMatchingRequest:
type: object
properties:
image1:
type: string
description: >-
First signature image. In JSON, a Base64-encoded image with or
without a data URI prefix (for example `data:image/png;base64,...`).
In `multipart/form-data`, an image file. Maximum 2 MB after
decoding. URLs are not accepted.
image2:
type: string
description: >-
Second signature image to compare against `image1`, in the same
accepted formats. Maximum 2 MB after decoding. URLs are not
accepted.
metadata:
type: object
additionalProperties: true
description: >-
Optional client-provided correlation data, echoed back on the
response.
example:
referenceId: SIGNATURE-MATCH-0001
required:
- image1
- image2
SignatureMatchingSuccessResponse:
type: object
required:
- success
- message
- data
- verificationStatus
- verificationStatusCode
- transactionId
- verificationType
- createdAt
properties:
success:
type: boolean
example: true
message:
type: string
example: Signature Matching processed successfully
data:
type: object
required:
- similarity
- verdict
- verdictDisplay
properties:
similarity:
type: number
description: >-
Similarity score between the two signatures. Higher values
indicate a closer match.
verdict:
type: string
enum:
- MATCH
- INCONCLUSIVE
- NO MATCH
description: >-
Match verdict. `MATCH` maps to `VERIFIED`, `INCONCLUSIVE` to
`REVIEW_NEEDED`, and `NO MATCH` to `REJECTED`.
verdictDisplay:
type: string
enum:
- Match
- Inconclusive
- No Match
description: Human-readable form of `verdict`.
verificationStatus:
type: string
enum:
- VERIFIED
- REVIEW_NEEDED
- REJECTED
verificationStatusCode:
type: integer
enum:
- 3
- 2
- 1
description: '`3` = Verified, `2` = Review Needed, `1` = Rejected.'
transactionId:
type: string
format: uuid
verificationType:
type: string
example: signature_matching
metadata:
type: object
additionalProperties: true
nullable: true
createdAt:
type: string
example: 2026-10-06 06:15:00+0000
SignatureMatchingValidationErrorResponse:
type: object
required:
- success
- code
- message
- errors
- transactionId
- verificationType
- createdAt
properties:
success:
type: boolean
example: false
code:
type: string
enum:
- VALIDATION_FAILED
message:
type: string
errors:
type: object
additionalProperties:
type: array
items:
type: string
transactionId:
type: string
format: uuid
nullable: true
description: Always `null`. Validation runs before a transaction is created.
verificationType:
type: string
example: signature_matching
createdAt:
type: string
SignatureMatchingErrorResponse:
type: object
required:
- success
- code
- message
- verificationStatus
- verificationStatusCode
- transactionId
- verificationType
- createdAt
properties:
success:
type: boolean
example: false
code:
type: string
enum:
- VALIDATION_FAILED
- SOURCE_UNAVAILABLE
description: >-
`VALIDATION_FAILED` when a submitted signature could not be
processed; `SOURCE_UNAVAILABLE` when the provider could not be
reached.
message:
type: string
verificationStatus:
type: string
example: FAILED
verificationStatusCode:
type: integer
example: 6
transactionId:
type: string
format: uuid
verificationType:
type: string
example: signature_matching
metadata:
type: object
additionalProperties: true
nullable: true
createdAt:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Use your API token as a Bearer token in the `Authorization` header.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.