1. Home
  2. Docs
  3. Data Subscriber API Documentation
  4. Tutorials
  5. Enroll Person and Authenticate

Enroll Person and Authenticate

In this tutorial, we will walk through how to use Pentadata’s Person enrollment and Auth product with your application.

Steps

  1. Retrieve a valid JWT
  2. Enroll Person
  3. Authenticate
  4. Verify

Retrieve a Token

To retrieve a valid token use the following endpoint

POST /subscribers/login

with a JSON body composed of email and api_key.

The API will respond with a token, and its expiration timestamp in UTC. It will also give you a “refresh_token” and its expiration timestamp.

  • When the token expires, use the refresh token to get a new one.
  • When the refresh token expires too, then you have to log in again with email and api_key.
  • See API Login for more information about out JWT’s.
const login = async() => {
    try {
        const res = await fetch(`${URL}/subscribers/login`, {
            method: 'POST',
            headers: new Headers({
                'Content-Type': 'application/json'
            }),
            body: JSON.stringify({
                email: 'email',
                api_key: 'api-key'
            })
        })
        const token_data = await res.json()
        console.log(token_data)
    }
    catch(err) {
        console.log('Error retrieving token', err)
    }
}

Use the JWT

Once you have got a valid JWT, which means you have been both authenticated and authorized, you must use it in the headers of every request you send. The headers of your requests should always be:

-H 'Content-Type: application/json' -H 'Authorization: Bearer $JWT'

Enroll Person

Before you can enroll a person using our API, you are responsible for capturing the person’s consent. Payload requirements:

  • email (str)
  • first_name (str)
  • last_name (str)
  • consent (str)
const enroll_person = async() => {
    try {
        const res = await fetch(`${URL}/persons`, {
            method: 'POST',
            headers: new Headers({
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${TOKEN}`
            }),
            body: JSON.stringify({
                email: 'Email',
                first_name: 'Jane',
                last_name: 'Doe',
                consent: 'Consent URL'
            })
        })
        const { person_id } = await res.json()
        console.log(person_id)
    }
    catch(err) {
        console.log('Error enrolling person', err)
    }
}

Authentication

Now that a person is enrolled, you will have a person_id to identify that person. You will need this to authenticate and verify the person. The next step is to send the person personal information to:

POST /persons/:id/authenticate

Required payload:

  • first_name (str)
  • last_name (str)
  • address (str)
  • city (str)
  • postal_code (str)
  • state (str)
  • country (str)
  • ssn (str) – last four of social
  • dob (str) – YYYY-MM-DD
  • phone (str)

See Authenticate for more details

const authenticate = async() => {
    try {
        const res = await fetch(`${URL}/persons/${id}/authenticate`, {
            method: 'POST',
            headers: new Headers({
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${TOKEN}`
            }),
            body: JSON.stringify({
                first_name: 'Jane',
                last_name: 'Doe',
                address: '123 St',
                city: 'San Francisco',
                postal: '94133',
                state: 'CA',
                country: 'US',
                ssn: '0001',
                dob: '1999-01-01',
                phone: '5550010001'
            })
        })
        const data = await res.json()
        console.log(data)
    }
    catch(err) {
        console.log('Error authenticating person', err)
    }
}

// Response

{
    "fulfillmentKey" : 'fulfillmeny-key',
    "questions" : [
       {
          "fullQuestionText" : "Which of the following is a current or previous employer?",
          "answerChoice" : [
             {
                "answerId" : "0000000001",
                "answerChoiceText" : "Company A"
             },
             {
                "answerId" : "0000000002",
                "answerChoiceText" : "Company B"
             },
             {
                 "answerId" : "000000003",
                "answerChoiceText" : "Compoany C"
             },
             {
                 "answerId" : "000000004",
                "answerChoiceText" : "Company D"
             },
             {
                 "answerId" : "000000005",
                "answerChoiceText" : "None of the Above"
             }
          ],
          "questionId" : "000000QID"
       }
    ]
 }

Verify

This step is required to verify the identity of the person. Use questionId and answerId from the previous request.

POST /persons/:id/verify

Required payload:

  • answers – (list)
  • fulfillment_key (str) – found in response of /authenticate

See Verify for more details.

const verify = async() => {
    try {
        const res = await fetch(`${URL}/persons/${id}/verify`, {
            method: 'POST',
            headers: new Headers({
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${TOKEN}`
            }),
            body: JSON.stringify({
                fulfillmentKey: 'fulfillment-key',
                answers: [
                            {
                                "questionId": "0000000001",
                                "answerId": "000000QID"
                            }
                        ]
            })
        })
        const data = await res.json()
        console.log(data)
    }
    catch(err) {
        console.log('Error verifying person', err)
    }
}

That’s it! If the person is verified, you will receive a 202 response. In some cases you may get a 200 response, the person will need to answer additional questions to complete the verification process. To complete this, repeat the verification step.

How can we help?