Performing an identity verification

In this guide you will learn how to perform an identity verification on an audio, against one of the voiceprints of an identity.

If you are unfamiliar with these concepts, follow their links or read the API reference introduction.

✦ Goal: perform an identity verification and obtain its score.

Prerequisites

Set up your HTTP client

Use the playground or automatically generate requests from the OpenAPI definition.

Authenticate using your credentials or API keys

Your API requests must be authenticated using your credentials or API keys.

Gain access to a space

You can only operate in spaces that belong to your user or to one of your organizations. Review these relationships if your access is denied.

→ owner space

Create an identity

You must have created an identity in the chosen space.

→ identity

Compute a voiceprint

You must have computed a voiceprint for the created identity.

→ voiceprint

Upload an audio

You must have uploaded an audio to the chosen space.

→ audio

Procedure

Perform the identity verification

Perform the identity verification on the uploaded audio with the chosen model, providing the target identity and its selected voiceprint. See the API reference.

← owner space audio identity voiceprint

Optionally, you may choose the alias for the verification.

In identity verifications, an appropriate model for the voiceprint is automatically selected.

In verifications, the latest model version is automatically selected.

→ ✦ verification model version ✦ score

In verifications, confidence in a positive result is represented by their scores. Learn more.

Request
Response

Method — POST
Path — /spaces/{owner}/{space}/verifications/identity
Body — application/json

{
  "audio": "{audio}",
  "identity": "{identity}",
  "voiceprint": "{voiceprint}"
}

Code — 201
Body — application/json

{
  "id": "...",
  "handle": "{verification}",
  "alias": "...",
  "state": "performed",
  "model": "{model}/{version}",
  "audio": {
    "handle": "{audio}",
    "alias": "..."
  },
  "voiceprint": {
    "handle": "{voiceprint}",
    "alias": "...",
    "identity": {
      "handle": "{identity}",
      "alias": "..."
    }
  },
  "score": {score},
  "performedAt": "..."
}

Validation

Validate the identity verification details

To validate that the identity verification has been correctly performed, retrieve and analyze its details. See the API reference.

← owner space verification

Request
Response

Method — GET
Path — /spaces/{owner}/{space}/verifications/identity/{verification}

Code — 200
Body — application/json

{
  "id": "...",
  "handle": "{verification}",
  "alias": "...",
  "state": "performed",
  "model": "{model}/{version}",
  "audio": {
    "handle": "{audio}",
    "alias": "..."
  },
  "voiceprint": {
    "handle": "{voiceprint}",
    "alias": "...",
    "identity": {
      "handle": "{identity}",
      "alias": "..."
    }
  },
  "score": ...,
  "performedAt": "..."
}

Validate the verification usage records

To validate that the identity verification has been correctly performed, retrieve and analyze the verification usage records. See the API reference.

← owner

This step assumes that the owner is an organization. If you are the owner, you must use a slightly different endpoint. See the API reference.

Request
Response

Method — GET
Path — /orgs/{owner}/records/verification

Code — 200
Body — application/json

[
  ...,
  {
    "id": "...",
    "handle": "...",
    "actor": {
      "handle": "...",
      "alias": "..."
    },
    "type": "identity",
    "model": "{model}/{version}",
    "verification": {
      "handle": "{verification}",
      "alias": "...",
      "type": "identity"
    },
    "space": {
      "handle": "{space}",
      "alias": "...",
      "owner": {
        "type": "...",
        "handle": "{owner}",
        "alias": "..."
      }
    },
    "owner": {
      "type": "...",
      "handle": "{owner}",
      "alias": "..."
    },
    "performedAt": "..."
  },
  ...
]

Prerequisites​