> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wearepion.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Native Technical Documentation
## **Introduction**
This documentation provides a detailed explanation of how to integrate with Beans iD Whitelabel API - Native. It includes the steps you will go through for integration and provides reference points to the different API endpoints that you will utilise.
Our native implementation allows for a user to verify as a member of any of our supported consumer groups utilising your own native UI. You will interact with our various endpoints validate the information you collect from an individual enabling you to verify them as a member of a consumer group using your own UI backed up by our verification technology.
## **How does it work?**
The intended flow is as follows:
To conduct a verification, several requests must be made to the Pion API.
The Pion API provides an OAuth Client Credentials grant flow which returns an access token. Client credentials can be self-served in the Pion Portal. This will create a new pairing of a `clientId` and `clientSecret` that is used to fetch an access token that ***must*** be passed into requests that require authentication.
Once you’ve got client credentials, you can send a request to the `/auth/token` endpoint. See the full API documentation [here](/api-reference/authentication/generate-access-token).
To begin the verification process a request is sent to the Create Verification endpoint in the Pion API. See the full API documentation [here](/api-reference/beans-id-whitelabel-api/create-a-new-verification).
This will begin the verification process for your chosen consumer group, and will create a unique verification ID used to reference this verification going forwards.
The `verificationId` returned from this step **must** be saved against your user as a unique field. This ensures that this verification ID can only be used for the verification of the user it is associated with. It should be saves as a unique value.
Gather the user's phone number and use it to trigger the sending of a one-time passcode (OTP) to the user's phone number.
This can be done using the Trigger Phone OTP endpoint. See the full API documentation [here](https://docs.wearepion.com/api-reference/beans-id-whitelabel-api/trigger-phone-otp).
Collect the 6-digit code from the user to validate the phone identity. This is done by sending the code to the Verify Phone OTP endpoint. See the full API documentation [here](https://docs.wearepion.com/api-reference/beans-id-whitelabel-api/verify-phone-otp).
**Instant Verification:** The user may be instantly verified at the point the OTP is received if we are able to match them to an existing identity in our database.
Ensure you check the status property returned in the response. If it is `success` then the user is now verified, if it is `pending` then the user must continue through the process to verify.
Let the user search for their institution using the search endpoint. See the full API documentation [here](https://docs.wearepion.com/api-reference/beans-id-whitelabel-api/institution-search).
The institution the user selects will dictate the verification methods available to that user.
**Student Verifications**
For student verifications, we recommend implementing a live search using a combination of institution name and institution territory.
**Non-student Verifications**
For non-student verifications, we recommend searching via consumer group and allowing the user to select from the list of returned options. In certain territories for certain consumer groups only one institution may be returned in which case we recommend setting this automatically.
Update the ongoing verification session with the specific `institutionId` that was chosen or auto-selected for the user in the previous step.
This is done by passing the `institutionId` into the Set Institution endpoint. See the full API documentation [here](https://docs.wearepion.com/api-reference/beans-id-whitelabel-api/set-institution).
Once an institution has been set on a verification we can determine the verification methods available for the selected institution. The `availableMethods` array found in the response returned when setting the institution provides this information.
If `portal` is present in the available methods array, follow these steps:
1. **Trigger Portal Attempt:** Initialize the portal attempt using the [Create Portal Attempt endpoint](https://docs.wearepion.com/api-reference/beans-id-whitelabel-api/create-portal-attempt).
A registered redirect URL must be supplied and this URL must be registered against your application in Pion Portal.
2. **Open the institution portal:** Send the user directly to the `portalStartUrl` string returned in the response payload.
3. **Handle the redirect:** The user will complete their login via their institution portal and will be redirected automatically back to the redirect URL you supplied when initialising the attempt.
If `email` is present in the available methods array, follow these steps:
1. **Trigger the OTP:** Trigger a one-time passcode to be sent to the user's institutional email address using the [Create Email Attempt endpoint](https://docs.wearepion.com/api-reference/beans-id-whitelabel-api/create-email-attempt).
2. **Gather the OTP:** Collect the OTP from the user and send it to the [Verify Email OTP endpoint](https://docs.wearepion.com/api-reference/beans-id-whitelabel-api/verify-email-otp) to check it is correct.
If `manual` is present in the available methods array, follow these steps:
1. **Gather Evidence & Hash:** Collect the user's verification documents locally and generate a `sha256` hash of the file content to act as a unique fingerprint.
2. **Upload:** Upload the document metadata, hash, and base64 string content to us for review using the [Create Manual Attempt endpoint.](https://docs.wearepion.com/api-reference/beans-id-whitelabel-api/create-manual-attempt)
3. **Await Hook:** We will dispatch a webhook event to notify your system when the attempt is officially approved or rejected. See the full Webhook documentation [here](https://docs.wearepion.com/api-reference/beans-id-whitelabel-api/verification-webhook).
## Verification Status
Each verification has a `status`. The `status` is a top-level indicator that can be used to discern the current state of a verification.
When you encounter a user that already has a `verificationId` the `status` can be used to understand how to handle this user.
If the `status` is `pending` then you should consult the `stage` to understand where in the verification journey a user currently is.
If the `status` is `success` then the verification was successful and the user has been successfully verified as a member of the given consumer group.
You should ensure you have provisioned a verified status to your user and that they are able to access any features or perks
If the `status` is `expired` then the verification was previously successful but the user's verification has since expired.
We will dispatch a webhook event to you in the event a verification expires. You can choose to handle the expiry event as you see fit.
If the `status` is `failed` then the user did not verify in time or hit verification limits.
You are welcome to create another verification for this user and let them try again, or you can decide to limit the number of verifications a user can attempt.
## Verification Stages
Alongside a `status` each verification also has a `stage`.
The `stage` is a more granular indicator of the specific step of the verification flow that a verification currently occupies. The below diagram lays out the different stages a verification can go through and the actions that need to be taken for a verification to move from stage to stage.
