1. Home
  2. Docs
  3. Data Subscriber API Documentation
  4. Auth (via Banking)

Auth (via Banking)

Auth (via Banking) is our API product that enables you to verify a user identity with their banking information.

You can use it together with, or at the place of, our other Auth product (that works with phone number and partial SSN).

The good news: Auth (via Banking) requires just one API call from you to us. The endpoint is /persons/:id/auth. Here’s how it works.

First, you send a request to POST /persons/:id/auth with the user first name, last name and (optionally) address. This is the information that you’d like to know if are correct, or not. You must have already created a Person resource for this user (with POST /persons).

At this point, if we have already verified this Person’s information with any of our data sources, then we’d tell you right away: name is correct, or name is not correct.

It can happen that we haven’t verified this Person yet. In such a case, we will send you a secure link where the user will have to confirm their banking information. After that, we will automatically check with the partner banks the user name and address. The good news is that this is fully automated and it happens asynchronously, so neither you nor your user must wait in front of the screen.

The question then is: if everything is magically done asynchronously, then how would you know? Simple: just call the same endpoint again, at any time. Like said, the endpoint will return you a banking link redirect only if the user didn’t verify it yet. If they did, we give you the response right away. This means that you can simply fetch the same endpoint POST /persons/:id/auth. You can retry as many times you want, because you pay only for the times the connection to the banks are established.

What about real-time notifications? We send those too. If you have registered a secure webhook endpoint when you onboarded with Pentadata, then we would send the instant notification of the registered Auth process, so you can ping the endpoint right then.

Next follow the technical specification of the endpoint.

Response code

The response contains a “code” key, with an integer value that has the following meanings:

  • “0” means the personal information are correct and the user identity is verified.
  • “1” means the personal information are wrong. The name the user gave you doesn’t match the bank account’s name.
  • “2” means the authentication started, and the response also contains the “url” key.
  • “3” means authentication is in progress, wait a bit and retry.

Webhook format

For this product we send you a real-time alert when the user has completed the authentication with our bank partner. This is the payload format we send in the webhook.

{
  "event": "auth",
  "person_id": 83544785,
}

When you receive it then you should call POST /persons/:id/auth to confirm the user identity (or at least to know that it’s not verified!).

Don’t forget to check that the webhook is legit, by comparing the “alert-token” you have in your account.

How can we help?