プロセスの取得GET

既存のプロセスを識別子で取得します。APIコントラクトの仕様上、結果はプロセス作成時にすでに同期的に返されているため、このエンドポイントは再照会・監査・サポート対応に使用します。

警告

プロセスを取得する前に、Webhookの設定とフォールバック戦略を確認してください — こちらをクリック。

エンドポイント

環境	URL
本番	GET https://api.id.unico.app/processes/v1/{processId}
サンドボックス	GET https://api.id.uat.unico.app/processes/v1/{processId}

リクエスト

ヘッダー

ヘッダー	値
Authorization	Bearer <access_token>
APIKEY	発行済みのAPIキー。

パスパラメータ

パラメータ	型	必須	説明
processId	string (UUID)	はい	プロセスの作成で返されるプロセス識別子。

例

cURL

curl -X GET https://api.id.unico.app/processes/v1/$PROCESS_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.id.unico.app/processes/v1/${processId}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const result = await res.json();

レスポンス

200 OK

このコントラクトは単一で、idCloud.result フィールドが使用されたケイパビリティの統合された判定結果を保持します。

Unicoは、実行されたケイパビリティの結果を単一の idCloud.result に統合します。個々の結果をオーケストレーションする必要はなく、フローの次のステップをすぐに判断できます。

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

フィールド	型	説明
id	string (UUID)	プロセス識別子。
status	integer	1（処理中）、2（不一致）、3（正常終了）、4（キャンセル）、5（エラー）。

可能な結果の値

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

返される値は、APIKeyに設定されたレシピによって異なります。各レシピが返す結果値については、フローを参照してください。

ブラジルのクライアントはケイパビリティ単位のレスポンスを受け取る場合があります

全体のレスポンス構造は変わらず、単一の結果がデフォルトです。

ブラジルの統合はケイパビリティごとに開かれた結果を受け取る場合があります。APIKeyで有効化された各ケイパビリティがレスポンスに独自のブロックを追加し、無効なケイパビリティのフィールドは省略されます。

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "riskLevel": {
    "result": "inconclusive"
  },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  },
  "government": {
    "serpro": 87
  },
  "liveness": 1,
  "idAge": {
    "result": "yes"
  },
  "cardholderVerification": {
    "result": "approved"
  }
}

フィールド	型	説明
unicoId.result	string	yes、no、inconclusive — 本人確認を参照してください。
riskLevel.result	string	not_approved、critical_risk、high_risk、inconclusive — 不正リスク分類を参照してください。
idFace.result	string	FOUND — 顔識別子を参照してください。
idFace.personId	string	顔に対する安定した不透明な識別子。idFace.result = FOUND とともに返されます。画像内で顔を識別できない場合、プロセスは idFace ブロックの代わりにエラー 20532 を返します。
identityFraudsters.result	string	非推奨。 代わりに riskLevel を使用してください。既存の統合を持つクライアントは、プロジェクトチームと移行を調整しながら引き続き使用できます。
government.serpro	integer	Serpro類似度スコア（0〜100、-1、-2）。ブラジルのみで利用可能。Serpro類似度返却を参照してください。
liveness	integer	1（合格）、2（不合格） — ライブネスを参照してください。
idAge.result	string	yes、no、inconclusive — 年齢確認を参照してください。ブラジルのみで利用可能。
score	integer	確率的リスクスコア。unicoId.result = inconclusive かつリスクスコアのオーケストレーションが有効な場合に存在します。正の値は本人である確率が高いことを示し、負の値はリスクが高いことを示します。ブラジルのみで利用可能。
cardholderVerification.result	string	approved、unsure — Cardholder Verificationを参照してください。status が 3（完了）になるまでは存在しません。ブラジルのみで利用可能。

このエンドポイントの使用タイミング

APIコントラクトは結果を同期的に返すため、ほとんどの統合ではこのエンドポイントは不要です。次の場合に使用します。

• processId のみを保存しており、後で完全な結果を取得する必要がある場合（監査、サポート対応）。
• 元のレスポンスが通信中に失われた可能性がある場合（プラットフォームが処理を完了した後のネットワークエラー）。
• 過去のプロセスを確認するバックオフィスツールを構築している場合。

エラーコード

400 Bad Request

コード	メッセージ	説明
20023	O parâmetro processId não foi informado.	processId パラメータが指定されていません。
20002	O parâmetro APIKey não foi informado.	リクエストヘッダーにAPIKEYパラメータがありません。
20001	O parâmetro authtoken não foi informado.	リクエストヘッダーに統合トークンパラメータがありません。

404 Not Found

コード	メッセージ	説明
50001	O processo informado não foi encontrado.	指定されたプロセスがデータベースに存在しません。

403 Forbidden

コード	メッセージ	説明
30017	User does not have permission to perform this action.	JWTが不正であるか、この操作を実行する権限がないユーザーです。
10502	O token informado está expirado.	使用されたアクセストークンの有効期限が切れている場合。
10501	O token informado é inválido.	認証トークンが無効です。
10201	O AppKey informado é inválido.	APIKEYパラメータが入力されていないか、存在しません。

410 Gone

プロセスは存在しますが、エラーで終了しています。id と status: 5 のみを返します。

429 Too Many Requests

Rate limit reached. When your system receives an HTTP 429 error, you must implement mechanisms to prevent cascading failures and avoid worsening the restriction.

Best practices:

• Cool-down period (backoff): Immediately halt or throttle subsequent requests from your system. Do not continuously retry failed requests in a tight loop.
• Queueing & throttling: Buffer or queue outgoing requests on your end to control the traffic flow before re-sending them.
• Exponential backoff with jitter: When retrying, increase the waiting time exponentially between attempts (e.g., 1 s, 2 s, 4 s, 8 s) and add a small random delay ("jitter") to prevent a herd effect where all queued requests retry at the exact same millisecond.

警告

Continuously hitting a rate-limited endpoint without backing off can prolong the restriction period and severely impact your system's operational throughput. Properly throttling requests on your side ensures a smoother, more resilient integration.

For default limits, increase requests and additional details, see Rate Limits.

500 Internal Server Error

コード	メッセージ	説明
99999	Internal failure! Try again later	内部エラーが発生した場合。

フロー

レシピとは、プロジェクトのAPIKeyに設定されたケイパビリティ（ライブネス、本人確認、リスクシグナル、ドキュメントなど）の組み合わせです。各プロセスでUnicoが何を実行し、結果がどのように単一の result に統合されるかを定義します — お客様側でオーケストレーションを行う必要はありません。

Unicoは、名前とバージョンが付けられた事前定義済みレシピのカタログを管理しています（例: byunico-idlive-idunico-oneresponse-std）。Score、Serpro、年齢確認を含むものなど、一部はブラジル専用です。

プロセスはどのケイパビリティを実行しますか?

ケイパビリティの組み合わせ（プロジェクトのフロー）は、APIKeyの設定で定義されます。事前定義済みのレシピを確認するか、Unicoのプロジェクト担当者にカスタマイズを相談してください。