post
https://api.useoval.com/entity_onboarding
POST /entity_onboarding
Start an asynchronous onboarding for one person. Use a stable reference to retry a request safely. A live completion returns the created or matched person ID. A test completion produces a synthetic person without a live identity check.
Use a server-side bearer key for the same organisation and environment. See Authentication.
The only required field is entity_type with the value person. The body accepts up to 8 KiB and rejects unknown properties.
| Body field | How to use it |
|---|---|
reference | Supply a stable, case-sensitive value up to 128 UTF-8 bytes, without surrounding whitespace. On retry, send the same inputs. |
email | Optional email prefill, up to 254 bytes. |
phone | Optional E.164-style phone prefill, for example +12025550142. |
sandbox_scenario | Test key only. Choose success (default), rejected or expired_link. |
Request
{
"entity_type": "person",
"reference": "applicant-0042"
}
Response · HTTP 202
{
"message": "Onboarding accepted",
"data": {
"id": "10000000-0000-4000-8000-000000000042",
"entity_type": "person",
"reference": "applicant-0042",
"status": "pending",
"status_reason": null,
"person_id": null,
"created_at": "2026-11-01T12:00:00Z",
"updated_at": "2026-11-01T12:00:00Z",
"actions": []
}
}
Errors
| HTTP | What to check |
|---|---|
| 400 | Check the JSON fields and contact formats. Only person is supported. Provide a sandbox scenario only with a test key. |
| 401 | Invalid credentials or organisation access |
| 409 | Fetch the onboarding by reference; retry with the original inputs or use a new reference for a separate onboarding. |
| 500 | Graph could not process the request. Fetch the current state before retrying; reuse the same reference if the create result is uncertain. |
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Invalid credentials or organisation access