プロセスの作成POST

プロセスを開始し、Human Token と本人のインテリジェンスを取得します。

Markdown

POST /v1/processes

フローのいずれかでプロセスを開始し、id、state、および data 内の結果(Human Token と本人のインテリジェンスである data.ndocs)を返します。

呼び出す前に

• Human Plugin が稼働しており、GET /health/ready が 200 を返します。
• アクセスキーが、使用するフローに対して有効化されています。
• 書類を送信する場合、その type が属性カタログにあります。

フロー

flow フィールドで、プロセスが何を行うかを選択します。Human Plugin は次のフローを、2 つの連携モデルで実行します。

• API Only: バックエンドが imageBase64 で自撮りを送信し、作成リクエストが結果を返します。
• Human Token Journey: 本人がキャプチャ Journey で自撮りを行い、callbackUri に戻ります。作成リクエストは token と link を返し、結果はプロセスの取得で読み取ります。

Flow	Description	Possible result	Integration components required	Example
api+humantoken	バックエンド経由で自撮りを受け取り、一意の顔識別子である Human Token を生成します。レスポンスが最終結果です。キャプチャも 2 回目の呼び出しもありません。	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
humantoken	キャプチャ Journey でライブネスチェックとともに自撮りをキャプチャし、Human Token を生成します。作成リクエストは `token` と `link` を返します。キャプチャが終了したら結果を読み取ります。	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb
humantoken+revalidation	自撮りをキャプチャし、期待する Human Token と顔を照合します。同一人物かどうかを返します。たとえば重要な操作の前に使用します。	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb

clientId、correlationId、credential は、どのフローでも共通です。

リクエスト

{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<base64 selfie>"
}

共通フィールド

フィールド	必須	上限(バイト)	備考
flow	はい	64	フローのいずれか
clientId	はい	128	クライアントを識別する、お客様側の ID。インテリジェンスは異なる値の数を集計します
correlationId	はい	128	このプロセスに対する、お客様側の参照。一意である必要があります。状態にかかわらず、別のプロセスがすでに持っている値は 409 で拒否されます
credential	はい(ただし空でも可)		キーは必ず存在する必要があります。下記を参照
credential.type	書類がある場合		属性カタログのコード。完全一致で、大文字と小文字を区別します
credential.value	書類がある場合	64	書類番号

flow、clientId、correlationId は文字列で、制御文字や前後の空白を含んではいけません。無効な値は拒否され、書き換えられることはありません。

credential フィールド

• 書類がある場合: type と value だけを持つオブジェクトで、どちらも文字列として一緒に送信します。
• 書類がない場合: null または {}。この場合でも、プロセスはインテリジェンス上でトランザクションおよびクライアントとして数えられます。
• 省略、または空文字列のオブジェクト: 400 MISSING_CREDENTIAL_TYPE で拒否されます。これにより、何かが処理される前にキーの綴りミスを検出できます。
• credential 内のその他のキーは拒否されます。

フローのフィールド

各フローが共通フィールドに追加するもの:

フィールド	フロー	必須	値
imageBase64	api+humantoken	はい	base64 形式の自撮り。PNG、JPEG、WebP のいずれかで、最大 800 KB
callbackUri	humantoken、humantoken+revalidation	はい	キャプチャ終了時に本人が戻る先。お客様のページ、またはアプリの URL スキーム
references	humantoken+revalidation	はい	上の例のように、期待する Human Token を持つ 1 件の項目

Human Plugin はこれらのフィールドを保存しません。また、綴りを誤った任意フィールドは、エラーなしに無視されることがあります。

api+humantoken では、正面から明るい環境で撮影した、顔が 1 つだけ写っている自撮りを使用してください。画像でない値は拒否され、プロセスは失敗として保存されます。フローによる拒否を参照してください。

humantoken+revalidation では、結果に humanToken の代わりに humanTokenMatch が含まれます。

• "true": 同一人物です。プロセスはその人物のものとして数えられ、ndocs はその人物を表します。
• それ以外、またはライブでないキャプチャ: 確認できません。プロセスは誰のものとしても数えられず、ndocs もありません。

どちらの場合も PROCESS_STATE_FINISHED が返されます。humanTokenMatch を読み取ってください。プロセスの取得を参照してください。

clientReference など、Human Plugin が予約している名前は、400 INVALID_REQUEST で拒否されます。client_id、correlation_id、Flow など、Human Plugin 自身のフィールドの別の綴りも同様です。読み取られるのは、flow、clientId、correlationId、credential だけで、綴りも正確にこのとおりである必要があります。

ボディのルール

• JSON オブジェクト 1 つで、最大 2 MiB(base64 形式の自撮り 1 枚が収まる程度)です。これより大きいボディは 400 REQUEST_TOO_LARGE で拒否されます。
• JSON オブジェクトの後ろに何も続けてはいけません。

レスポンス

201 Created。Location: /v1/processes/<id> が付きます。

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}

• id は Human Plugin の UUID です。受理されたリクエストごとに新しいものが作成されます。
• state はローカルのステータスです。ライフサイクルを参照してください。
• humantoken と humantoken+revalidation は、token と link を伴う PROCESS_STATE_CREATED を返します。これらは1 回だけ返され、保存されることはありません。必ず保管してください。Human Token Journeyと、お使いのプラットフォーム向けのキャプチャガイドを参照してください。
• data.ndocs は本人のインテリジェンスです。存在しない場合もあります。インテリジェンスを参照してください。

data 内の結果

完了したプロセスの data には、次のフィールドが含まれます。Journey フローでは、キャプチャ後にプロセスを読み取ると、これらが返されます。

フィールド	条件	値
humanToken	api+humantoken、humantoken	本人が誰であるか。value は Human Token で、生成された場合は status が validated になります
humanTokenMatch	humantoken+revalidation	references の Human Token と同一人物の場合は "true"
liveness	Journey フローなど、ライブネスを確認するフロー	キャプチャが生身の人物によるものであれば value は live、そうでなければ not_live。チェックが実行された場合、status は validated になります
ndocs	本人のインテリジェンスがある場合	本人のインテリジェンス

Journey の結果は次のようになります。

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}

結果を信頼する前に liveness を確認してください。not_live の場合は、キャプチャが失敗したものとして扱い、本人にもう一度試してもらってください。not_live のプロセスは、誰のインテリジェンスにも数えられません。

エラー

ステータス	message	意味
400	INVALID_REQUEST, REQUEST_TOO_LARGE	JSON オブジェクト 1 つではない、予約フィールド、型の誤り、または 2 MiB を超えるボディ
400	MISSING_<FIELD>, INVALID_<FIELD>	必須フィールドがない、または形式が不正です(例: MISSING_CLIENT_ID)
401	空("")	Unico がアクセスキーを拒否しました。キーが未指定、誤り、または無効になっています。プロセスは失敗として保存されます。HUMAN_API_ACCESS_KEY を確認してください
409	CORRELATION_ID_ALREADY_USED	別のプロセスがすでにその correlationId を使用しています。何も保存・送信されません
422	ATTRIBUTE_TYPE_NOT_SUPPORTED	credential.type がカタログにありません。何も保存・送信されません
4xx	フローの message	フローがリクエストを拒否しました(例: 無効な画像)。フローによる拒否を参照してください
502	UPSTREAM_UNAVAILABLE	プロセスを時間内に確認できませんでした
503	DATABASE_UNAVAILABLE	データベースで障害が発生しました。何も処理されていません
500	INTERNAL	予期しないエラー

フローによる拒否

フローがリクエストを拒否した場合、作成リクエストは 4xx を返し、理由は通常のエンベロープの message に入ります。よくあるものは次のとおりです。

message	原因
invalid flow	flow が、お客様のアカウントで有効なフローではありません
INVALID_IMAGE (400)	api+humantoken で imageBase64 がありません
INVALID_REQUEST (400)	imageBase64 が base64 形式の画像ではありません
IMAGE_TOO_LARGE	画像が 800 KB を超えています
UNSUPPORTED_IMAGE_FORMAT	画像が PNG、JPEG、WebP のいずれでもありません
PERMISSION_DENIED (403)	アクセスキーが、このフローに対して有効化されていません

拒否されたプロセスは失敗として保存されます。リクエストを修正し、新しい correlationId で新しいプロセスを作成してください。

リトライ処理を追加する前に、エラーとリトライをお読みください。新しい試行には新しい correlationId が必要です。

次へ

プロセスの取得