Intergiro developer portal

# Onboarding as a Service

Individuals represent end users and it's important to have them properly registered before they can use accounts or cards. This process is called onboarding.

# Create individual

The first step is to provide some basic personal information about an individual.

Example create individual request:

 



















POST /v3/individuals

Content-Type: application/json
Authorization: Bearer <access_token>

{
  "first_name": "John",
  "last_name": "de Mayor",
  "email": "m6dreey@goes.es",
  "phone_number": "46627211111",
  "date_of_birth": "1991-12-06",
  "address": {
  	"country_code": "SE",
  	"street1": "Mälarö torg 2",
  	"city": "Ekerö",
  	"region": "Ekerö",
  	"postal_code": "178 30"
  }
}

Address is optional.

Once created, you can query an individual by calling GET /v3/individuals/:id.

# Initiate onboarding

Onboarding process involves redirecting the end user to an URL, where we collect all necessary information required to open an account.

# Obtaining onboarding form URL

First you'll need to initiate individual onboarding to get the redirect_url:

 






 

POST /v3/individuals/9c017aec-c952-4713-aa10-11708cb0d11a/onboard

Content-Type: application/json
Authorization: Bearer <access_token>

{
  "return_url": "https://example.com/onboarding_callback"
}

Response:

 


 



HTTP 200 OK

{
  "redirect_url": "https://integrate.intergiro.com/onboarding/...",
  "expires_at": "2021-02-08T14:09:15.000Z"
}

# Sending the user to the form

Now you'll need to open the browser and send the user to the redirect_url provided earlier.

TIP

Consider using iOS SFSafariViewController (opens new window) and Android Chrome Custom Tabs (opens new window) in-app or standalone browser experience to take advantage of a more streamlined process using native Biometry support on mobile.

Once initiated, wait for IndividualOnboardingDataProvided webhook event that will be delivered as soon as the user successfully completes the form. That will mean the ball is on Intergiro side as we'll be receiving the data for approval.

# Getting notified about the result

# Data provided

Once the user submits all neccessary information a webhook is sent and individual's status changes to onboarding_data_provided.

Example IndividualOnboardingDataProvided event webhook payload:

{
  "id": "d08fb891-40be-4579-90c4-92c648b973f0",
  "name": "IndividualOnboardingDataProvided",
  "created_at": "2021-02-08T14:09:15.000Z"
}

Use the id from the webhook to get more details about the event.

Example IndividualOnboardingDataProvided event payload:

 




GET /v3/events/d08fb891-40be-4579-90c4-92c648b973f0

Content-Type: application/json
Authorization: Bearer <access_token>

Response:

 










HTTP 200 OK

{
  "id": "d08fb891-40be-4579-90c4-92c648b973f0",
  "name": "IndividualOnboardingDataProvided",
  "payload": {
  	"individual_id": "bd4af0ff-0a72-4e09-b247-c6d8c2391496"
  },
  "created_at": "2021-02-08T14:09:15.000Z"
}

WARNING

There may be cases when the user drops off without completing the form or doing something similar. For this reason it is recommended that you periodically check individuals who have stuck in onboarding_requested status, and send them to the onboarding form by calling POST /individuals/:id/onboard once again.

# Onboarding complete

Eventually, depending on the outcome, you'll receive another webhook event saying the individual was successfully onboarded (IndividualActivated event) or rejected (IndividualBlocked event).

Example IndividualActivated event webhook payload:

{
  "id": "859edbaa-e110-482d-9054-1d187179aaee",
  "name": "IndividualActivated",
  "created_at": "2021-02-08T14:09:15.000Z"
}

Use the id from the webhook to get more details about the event.

Example IndividualActivated event payload:

 




GET /v3/events/859edbaa-e110-482d-9054-1d187179aaee

Content-Type: application/json
Authorization: Bearer <access_token>

Response:

 










HTTP 200 OK

{
  "id": "859edbaa-e110-482d-9054-1d187179aaee",
  "name": "IndividualActivated",
  "payload": {
  	"individual_id": "bd4af0ff-0a72-4e09-b247-c6d8c2391496"
  },
  "created_at": "2021-02-08T14:09:15.000Z"
}

# Troubleshooting

# The URL doesn't work in an <iframe>

We do not support iframes and you should not try to embed the url but rather send the user to it.

# We do not collect user's address, can we skip it?

Yes, address section of POST /v3/individuals request body is optional.

# User provided incorrect details before or during onboarding, can we change the details?

Email or phone number can be changed with request PATCH /individuals/:id for individual who is in the process of onboarding and for individual who is onboarded (status is activated). For any other details change, please contact our support team.

← Accounts →