|

API

Onboard onto a playbook

post/onboardings
Preview

For an existing user or business, creates an onboarding onto the provided playbook and runs it headlessly with any data provided. Accepts prerequisite_data required by the playbook.

When synchronous_timeout_secs is provided, the decision is returned inline; otherwise the onboarding runs in the background and the result is delivered via webhook. If the run is incomplete, continue_onboarding contains a token and link to finish the flow interactively.

To get the status of an onboarding created via this API, use GET /onboardings/{id}.

For more information, see here.

Request

Body

Run one of your playbooks on an existing user or business. The playbook executes as far as it can with the data already in the entity's vault and returns either the decision or a continue_onboarding token that lets the user finish the remaining steps in a Footprint flow.

external_id·

optional string

The identifier in your own database of the user or business for which you'd like to run this onboarding. This is used as an idempotency ID. Cannot be provided alongside fp_id

fp_id·

optional string

The fp_id of the user or fp_bid of the business for which you'd like to run this onboarding. Cannot be provided alongside external_id.

key·

string

The key of the playbook to onboard onto, optionally version-tagged (e.g. pb_live_xxx:v3).
prerequisite_data·

optional object

Optionally, any initial onboarding data to start with. This data will be available in template contexts and branch nodes under the data. prefix. Note: only keys listed on the playbook's prerequisite node are available in the playbook. Any other key is discarded, and the value of each key must match the schema declared there.

synchronous_timeout_secs·

optional integer

When provided, runs the onboarding synchronously with the provided timeout. When not provided, this API immediately returns once the onboarding is queued to execute asynchronously. Must be greater than 0 and cannot exceed 30 seconds. If the timeout is reached, execution will continue in the background and you'll receive an update via webhooks.

Response

continue_onboarding·

optional object

expires_at·

string

link·

string

A Footprint link embedding the token that can be sent to this user to allow them to complete the flow. This is useful to send in an automated message to the end user.

token·

string

A short-lived onboarding session token for the user to continue their onboarding flow. NOTE: treat this token as a secret.

error_message·

optional string

If the onboarding failed, the error message from the execution.
id·

string

output·

optional object

The output declared by your playbook's Output node, keyed by the names you configured there. Absent when your playbook declares no output or when the onboarding hasn't yet reached the Output node. Fetch the onboarding again once it completes to read it.

requires_manual_review·

boolean

status·

string

The decision for this onboarding issued by the Action nodes on your playbook. For more information on interpreting statuses, see here.

Allowed values:

pass
fail
incomplete
pending
none
error
POST /onboardings
1curl -X POST https://api.onefootprint.com/onboardings \
2  -u sk_test_xxxxx: \
3  -d '{
4    "external_id": "c0a801f2-7a97-4c0b-9b4c-4ac3e8b1e9a4",
5    "fp_id": "fp_id_7p793EF07xKXHqAeg5VGPj",
6    "key": "pb_live_fZvYlX3JpanlQ3MAwE45g0",
7    "prerequisite_data": {
8      "transaction_amount": 1000
9    }
10  }'
Response example
{
  "continue_onboarding": {
    "expires_at": "2022-01-04T12:00-07:00",
    "link": "https://verify.onefootprint.com/?type=user#obtok_ssPvNRjNGdk8Iq9qgf6lsO2iTVhALuR4Nt",
    "token": "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH"
  },
  "id": "id_nDtKC0iGmi3klqpHJd5KoS",
  "requires_manual_review": true,
  "status": "pass"
}