Skip to content

Base url

https://api-sandbox1.pawapass.com

Access

You will need an authorization key to access the pawaPass API. To get the key, please contact us and provide a valid URL for webhooks (see Webhooks). We will pass the new API key to you using a 1password vault.

Authorization

To authorize calls to pawaPass API endpoints, use a header with the integration auth key.

{
  "Content-Type": "application/json",
  "X-Auth-Key": "..."
}

Pagination

All endpoints which return a list of objects are paginated. You can control the pagination using query params:

?page=5&limit=20
where:

Name Type Description
page number, default 0, min 0 number of page to return
limit number, default 15, min 0, max 50 number of results per page

If you need to know the total number of results, you can find it in the count field in the response.

Endpoints

Get partner details

Get authorized partner details.

GET /partners

Response

{
  "id": "85fcc4b4-e4f8-44a4-a101-7fa16ab5416c",
  "webhookUrl": "https://your-webhook-url.com",
  "name": "partner name",
  "createdAt": "2023-04-03T12:04:28.325Z",
  "updatedAt": "2023-04-03T12:04:28.325Z"
}
where:

Name Type Description
id (string) string unique partner id
webhookUrl (string) string partner webhook URL (see Webhooks)
name string partner name
createdAt datetime partner creation time
updatedAt datetime partner last update time

Update partner details

Update authorized partner details.

PUT /partners

Request body

{
  "webhookUrl": "https://your-new-webhook-url.com"
}

Response

{
  "id": "85fcc4b4-e4f8-44a4-a101-7fa16ab5416c",
  "webhookUrl": "https://your-new-webhook-url.com",
  "name": "partner name",
  "createdAt": "2023-04-03T12:04:28.325Z",
  "updatedAt": "2023-04-03T12:04:28.325Z"
}

List auth keys

Get list of auth keys.

GET /auth-keys
GET /auth-keys?page=5&limit=20

Response

{
  "authKeys": [
    {
      "id": "37e13cce-a38b-46c6-8236-8359ab53dd4b",
      "key": "5d369b35-ab23-4b0e-839e-ad208cd8089f",
      "active": true,
      "updatedAt": "2023-04-05T12:28:20.648Z",
      "createdAt": "2023-04-03T12:04:28.325Z"
    }
  ],
  "count": 1
}
where:

Name Type Description
id string unique auth key id
key string key for authorization (see Authorization)
active bool status whether the key is active or not
createdAt datetime auth key creation time
updatedAt datetime auth key last update time

Create a new auth key

Create a new auth key.

Warning

Creating a new auth key automatically invalidates the previous active one.

POST /auth-keys

Request body

{}

Response

{
  "authKeys": [
    {
      "id": "692a8f62-9ccf-44cd-bcf7-3caa724963f1",
      "key": "04757a79-f385-4e83-a097-260db02252c3",
      "active": true,
      "updatedAt": "2023-04-05T12:28:20.648Z",
      "createdAt": "2023-04-05T12:28:20.648Z"
    },
    {
      "id": "37e13cce-a38b-46c6-8236-8359ab53dd4b",
      "key": "5d369b35-ab23-4b0e-839e-ad208cd8089f",
      "active": false,
      "updatedAt": "2023-04-05T12:28:20.648Z",
      "createdAt": "2023-04-03T12:04:28.325Z"
    }
  ],
  "count": 2
}

Create a new verification session

Create a new verification session in pawaPass. The new session starts with status set to created. You can track changes related to it using webhooks.

POST /verifications

Request body

{
  "phoneNumbers": [
    {
      "phoneNumber": "+48790500480",
      "isVerified": true
    },
    {
      "phoneNumber": "+48608504333",
      "isVerified": false
    }
  ],
  "firstName": "John",
  "lastName": "Doe",
  "requirements": [
    { "type":  "firstAndLastName" },
    { "type": "dateOfBirth" },
    { "type": "document" },
    { "type": "phoneNumbers" }
  ],
  "externalUserId": "your-user-id-1-as-uuid",
  "redirectUrl": "https://your-url.com?success=true",
  "errorRedirectUrl": "https://your-url.com?success=false",
  "timeToExpiry": 10,
  "reason": "suspicious behavior",
  "author": "[email protected]",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}
where:

Name Type Description
phoneNumber string user's phone number (deprecated, replaced by phoneNumbers)
isPhoneNumberVerified bool whether phone number is already verified (and does not need to be verified by pawaPass) (deprecated, replaced by phoneNumbers)
phoneNumbers array of objects, optional user's phone numbers with information if phone is already verified by you
firstName string, optional user's first name provided by you
lastName string, optional user's last name provided by you
requireFirstAndLastName bool, optional whether first and last name are required by user (deprecated, replaced by requirements)
requirements array of objects, optional defines which types of data you want to receive from user verification (allowed types: firstAndLastName, dateOfBirth, document, phoneNumbers)
externalUserId uuid id assigned to the user by you
redirectUrl string url the user will be redirected to after a successful verification
errorRedirectUrl string, optional url the user will be redirected to in case of error (e.g. expired token)
timeToExpiry number, optional, min: 5, max: 43200, default: 10080 indicates after what time (in minutes) the verification will expire, default value is 10080 minutes (7 days)
reason string, optional, max-length: 200 verification reason (optional)
author string, optional, max-length: 100) who created verification (optional)
metadata object, optional key-value data that you can attach to the verification, up to 50 keys, each with names up to 40 characters and values up to 500 characters.

Response

A newly created verification

{
  "id": "85fcc4b4-e4f8-44a4-a101-7fa16ab5416c",
  "url": "https://app-sandbox1.pawapass.com/verify?token=eYjsajmvm6bsmUsmdGwKsv37s",
  "phoneNumber": "+48790500480",
  "isPhoneNumberVerified": true,
  "phoneNumbers": [
    {
      "phoneNumber": "+48790500480",
      "isVerified": true
    },
    {
      "phoneNumber": "+48608504333",
      "isVerified": false
    }
  ],
  "firstName": "John",
  "lastName": "Doe",
  "requireFirstAndLastName": true,
  "requirements": [
    {
      "type": "firstAndLastName"
    },
    {
      "type": "dateOfBirth"
    },
    {
      "type": "document"
    },
    {
      "type": "phoneNumbers"
    }
  ],
  "collectedRequirements": [
    {
      "type": "firstAndLastName",
      "result": null,
      "verified": false
    },
    {
      "type": "dateOfBirth",
      "result": null,
      "verified": false
    },
    {
      "type": "document",
      "result": null,
      "verified": false
    },
    {
      "type": "phoneNumbers",
      "result": null
    }
  ],
  "externalUserId": "your-user-id-1-as-uuid",
  "redirectUrl": "https://your-url.com?success=true",
  "errorRedirectUrl": "https://your-url.com?success=false",
  "reason": "suspicious behavior",
  "author": "[email protected]",
  "status": "created",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "validTo": "2023-03-27T12:19:43.960Z",
  "createdAt": "2023-03-27T11:49:43.959Z"
}
where new fields:

Name Type Description
id string unique verification session id
url string url which needs to be passed to the end-user to start verification
status string, enum: status-enum verification session status, for this endpoint status is always created
collectedRequirements array of objects data which are already collected from user, each object includes:
NameTypeDescription
typeenum: [firstAndLastName, dateOfBirth, document, phoneNumbers]requested data type
resultobject | array | nullobject or array with collected data (see example above), might be null if no data collected
verifiedboolean (optional)flag if data was verified by pawaPass or just provided by user
validTo datetime verification's expiration time
createdAt datetime verification's creation time

Note

  1. If there is an existing and open (status: created, started) verification for the requested phoneNumber, the old verification will be closed and a new one will be created.
  2. If there is an already inReview verification for the requested phoneNumber and externalUserId, the endpoint returns 409 Conflict status code with an appropriate error message.

Revert completed verification

Revert verification and all data which comes with the verification. It detaches user from verification.

Beta

Reverting verification is already in beta phase, where it is open to everyone for exploration and use. This means you have the opportunity to integrate the API into your projects and provide valuable feedback. During this stage, we are actively seeking user input to refine and enhance the API before its official release.

POST /verifications/revert

Request body

{
  "verificationId": "85fcc4b4-e4f8-44a4-a101-7fa16ab5416c",
  "author": "[email protected]"
}
Name Type Description
verificationId string verification id to be reverted
author string who calls to revert verification

Response

{
  "id": "85fcc4b4-e4f8-44a4-a101-7fa16ab5416c"
}

Note

  1. Only successfully completed verification (status: completed) might be reverted. Otherwise, the endpoint returns 409 Conflict status code with an appropriate error message.
  2. All data will be reverted (detached from user) only if there is no other successfully completed verification which provides the same data (externalUserId, phoneNumber, firstName, lastName).
  3. User will be deleted (and user.deleted webhook will be sent) if no more externalUserId is linked to the user.
  4. Verification status will be updated to reverted and verification.updated webhook will be sent.

List verifications

Get a list of verification sessions.

GET /verifications
GET /verifications?page=5&limit=20
GET /verification?phoneNumber=+48790500480,+4848790500481&externalUserId=your-user-id-1-as-uuid&status=created&userId=user-id-1,user-id-2&from=2023-08-10T15:00:00Z&to=2023-08-20T15:00:00Z&datetimeField=createdAt

Response

{
  "verifications": [
    {
      "id": "85fcc4b4-e4f8-44a4-a101-7fa16ab5416c",
      "url": "https://app-sandbox1.pawapass.com/verify?token=eYjsajmvm6bsmUsmdGwKsv37s",
      "phoneNumber": "+48790500480",
      "isPhoneNumberVerified": true,
      "phoneNumbers": [
        {
          "phoneNumber": "+48790500480",
          "isVerified": true
        },
        {
          "phoneNumber": "+48608504333",
          "isVerified": false
        }
      ],
      "firstName": "John",
      "lastName": "Doe",
      "requireFirstAndLastName": true,
      "requirements": [
        {
          "type": "firstAndLastName"
        },
        {
          "type": "dateOfBirth"
        },
        {
          "type": "document"
        },
        {
          "type": "phoneNumbers"
        }
      ],
      "collectedRequirements": [
        {
          "type": "firstAndLastName",
          "result": { "firstName": "John", "lastName":  "Doe" },
          "verified": false
        },
        {
          "type": "dateOfBirth",
          "result": { "dateOfBirth": "2002-03-27" },
          "verified": false
        },
        {
          "type": "document",
          "result": {
            "firstName": "John",
            "lastName": "Doe",
            "dateOfBirth": "2002-03-27",
            "placeOfBirth": "Warsaw",
            "nationality": "Polish",
            "serialNo": "ID123456",
            "expiryAt": "2039-03-21",
            "issuedAt": "2029-03-21",
            "issuingAuthority": null,
            "placeOfIssue": null
          },
          "verified": true
        },
        {
          "type": "phoneNumbers",
          "result": [
            {
              "phoneNumber": "+48790500480"
            },
            {
              "phoneNumber": "+48608504333"
            },
            {
              "phoneNumber": "+48608599000"
            }
          ]
        }
      ],
      "userId": null,
      "previousUserId": null,
      "externalUserId": "your-user-id-1-as-uuid",
      "redirectUrl": "https://your-url.com?success=true",
      "errorRedirectUrl": "https://your-url.com?success=false",
      "reason": "suspicious behavior",
      "author": "[email protected]",
      "status": "created",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "validTo": "2023-03-27T12:19:43.960Z",
      "updatedAt": "2023-03-27T12:19:43.960Z",
      "createdAt": "2023-03-27T11:49:43.959Z"
    }
  ],
  "count": 1
}
You can narrow down the results using query parameters.

where:

Name Type Description
phoneNumber comma separated string phone number assigned to the user, in the E.164 format
externalUserId comma separated uuid user id provided by you
userId comma separated uuid user id assigned by pawaPass
status comma separated string, enum: status-enum verification session status
from datetime in RFC3339 format results more recent than the given date
to datetime in RFC3339 format results not older than the given date
datetimeField createdAt,updatedAt,validTo field from/to works with

Get verification details

Get the details of a single verification session.

GET /verifications/:verificationId

Response

{
  "id": "85fcc4b4-e4f8-44a4-a101-7fa16ab5416c",
  "url": "https://app-sandbox1.pawapass.com/verify?token=eYjsajmvm6bsmUsmdGwKsv37s",
  "phoneNumber": "+48790500480",
  "isPhoneNumberVerified": true,
  "phoneNumbers": [
    {
      "phoneNumber": "+48790500480",
      "isVerified": true
    },
    {
      "phoneNumber": "+48608504333",
      "isVerified": false
    }
  ],
  "firstName": "John",
  "lastName": "Doe",
  "requireFirstAndLastName": true,
  "requirements": [
    {
      "type": "firstAndLastName"
    },
    {
      "type": "dateOfBirth"
    },
    {
      "type": "document"
    },
    {
      "type": "phoneNumbers"
    }
  ],
  "collectedRequirements": [
    {
      "type": "firstAndLastName",
      "result": { "firstName": "John", "lastName":  "Doe" },
      "verified": false
    },
    {
      "type": "dateOfBirth",
      "result": { "dateOfBirth": "2002-03-27" },
      "verified": false
    },
    {
      "type": "document",
      "result": {
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "2002-03-27",
        "placeOfBirth": "Warsaw",
        "nationality": "Polish",
        "serialNo": "ID123456",
        "expiryAt": "2039-03-21",
        "issuedAt": "2029-03-21",
        "issuingAuthority": null,
        "placeOfIssue": null
      },
      "verified": true
    },
    {
      "type": "phoneNumbers",
      "result": [
        {
          "phoneNumber": "+48790500480"
        },
        {
          "phoneNumber": "+48608504333"
        },
        {
          "phoneNumber": "+48608599000"
        }
      ]
    }
  ],
  "userId": null,
  "previousUserId": null,
  "externalUserId": "your-user-id-1-as-uuid",
  "redirectUrl": "https://your-url.com?success=true",
  "errorRedirectUrl": "https://your-url.com?success=false",
  "reason": "suspicious behavior",
  "author": "[email protected]",
  "status": "created",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "validTo": "2023-03-27T12:19:43.960Z",
  "updatedAt": "2023-03-27T12:19:43.960Z",
  "createdAt": "2023-03-27T11:49:43.959Z"
}

where:

Name Type Description
id string verification session id
status string, enum: status-enum) verification session status
redirectUrl string url to redirect to once verification session status changes to inReview, completed, or declined
externalUserId uuid user id provided by you
userId string, optional user id related to this verification, available only if status is completed
previousUserId string, optional previous user id related to this verification, available only if status is reverted
validTo datetime verification's expiration time

Get user activities in verification

Get user activities which took place during verification.

GET /verification/:verificationId/user-activities

Response

{
  "activities": [
    {
      "activity": "startSession",
      "sessionId": "0db15f5c-52de-11ee-be56-0242ac120002",
      "createdAt": "2023-03-27T11:49:43.967Z"
    },
    {
      "activity": "cameraIssue",
      "sessionId": "0db15f5c-52de-11ee-be56-0242ac120002",
      "createdAt": "2023-03-27T11:52:40.835Z"
    }
  ]
}
where:

Name Type Description
activities.activity string describes type of activity
activities.sessionId string session id, note: user can have multiple sessions in single verification
activities.createdAt datetime time when the activity took place

Get linked verifications by device

Get all verifications which were run by user on the same device as queried one.

GET /verifications/:verificationId/linked-by-device

Response

{
  "verificationId": "85fcc4b4-e4f8-44a4-a101-7fa16ab5416c",
  "linkedVerificationsByDevice": [
    {
      "deviceId": "vskyslv2qq",
      "verifications": [
        {"verificationId":"85fcc4b4-e4f8-44a4-a101-7fa16ab5416c"}
      ]
    },
    {
      "deviceId": "zrplxvbq7b",
      "verifications": [
        {"verificationId": "85fcc4b4-e4f8-44a4-a101-7fa16ab5416c"},
        {"verificationId": "794ebb2e-1a35-11ee-be56-0242ac120002"}
      ]
    }
  ]
}

where:

Name Type Description
verificationId string queried verification session id
linkedVerificationsByDevice object represents all devices linked to the queried verification and all verifications linked to each device
linkedVerificationsByDevice.deviceId string unique device identifier
linkedVerificationsByDevice.verifications array list of verifications linked to the device, including the queried verificationId

List webhooks for a verification

Get a list of webhooks related to a single verification.

GET /verifications/:verificationId/webhooks
GET /verifications/:verificationId/webhooks?page=5&limit=20

Response

{
  "webhooks": [
    {
      "id": "9e6cb90b-4d3a-4503-9174-de0b9f3baf77",
      "verificationId": "85fcc4b4-e4f8-44a4-a101-7fa16ab5416c",
      "type": "verification",
      "success": true,
      "payload": {
        "eventId": "2c84c97a-a76a-4881-9b6b-5a6b2fc7e8fc",
        "createdAt": "2023-03-27T11:49:43.967Z",
        "dataType": "verification",
        "eventType": "verification.created",
        "data": {
          "verificationId": "85fcc4b4-e4f8-44a4-a101-7fa16ab5416c",
          "status": "created",
          "redirectUrl": "https://your-url.com?success=true",
          "errorRedirectUrl": "https://your-url.com?success=false",
          "externalUserId": "your-user-id-1-as-uuid",
          "phoneNumber": "+48790500480",
          "isPhoneNumberVerified": true,
          "phoneNumbers": [
            {
              "phoneNumber": "+48790500480",
              "isVerified": true
            },
            {
              "phoneNumber": "+48608504333",
              "isVerified": false
            }
          ],
          "firstName": "John",
          "lastName": "Doe",
          "requireFirstAndLastName": true,
          "requirements": [
            {
              "type": "firstAndLastName"
            },
            {
              "type": "dateOfBirth"
            },
            {
              "type": "document"
            },
            {
              "type": "phoneNumbers"
            }
          ],
          "collectedRequirements": [
            {
              "type": "firstAndLastName",
              "result": { "firstName": "John", "lastName":  "Doe" },
              "verified": false
            },
            {
              "type": "dateOfBirth",
              "result": { "dateOfBirth": "2002-03-27" },
              "verified": false
            },
            {
              "type": "document",
              "result": {
                "firstName": "John",
                "lastName": "Doe",
                "dateOfBirth": "2002-03-27",
                "placeOfBirth": "Warsaw",
                "nationality": "Polish",
                "serialNo": "ID123456",
                "expiryAt": "2039-03-21",
                "issuedAt": "2029-03-21",
                "issuingAuthority": null,
                "placeOfIssue": null
              },
              "verified": true
            },
            {
              "type": "phoneNumbers",
              "result": [
                {
                  "phoneNumber": "+48790500480"
                },
                {
                  "phoneNumber": "+48608504333"
                },
                {
                  "phoneNumber": "+48608599000"
                }
              ]
            }
          ],
          "userId": null,
          "validTo": "2023-03-27T12:19:43.960Z",
          "createdAt": "2023-03-27T11:49:43.959Z",
          "updatedAt": "2023-03-27T11:49:43.959Z"
        }
      },
      "retryAt": null,
      "reason": "suspicious behavior",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "updatedAt": "2023-03-31T13:10:28.193Z",
      "createdAt": "2023-03-31T13:09:37.076Z"
    }
  ],
  "count": 1
}
where:

Name Type Description
success bool whether the webhook was successfully delivered to your webhook endpoint
retryAt datetime when the next retry of the webhook's delivery is planned

Note

In case of retries, we will update the success, retryAt and updatedAt fields in an existing webhook rather than creating a new one.

List users

Get a list of your users verified by pawaPass.

GET /users
GET /users?page=5&limit=20
GET /users?phoneNumber=+48790500480,+4848790500481&externalUserId=your-user-id-1-as-uuid&id=id-1,id-2&isShareholder=true

Response

{
  "users": [
    {
      "id": "79e38018-fb04-4e13-a6e3-e49834840d82",
      "phoneNumbers": [
        {
          "phoneNumber": "+48717016015",
          "createdAt": "2023-04-03T11:30:37.616Z",
          "verified": true
        }
      ],
      "externalUsers": [
        {
          "id": "your-user-id-1",
          "createdAt": "2023-04-03T11:30:37.663Z"
        }
      ],
      "updatedAt": "2023-03-31T13:10:28.193Z",
      "createdAt": "2023-03-31T13:09:37.076Z"
    }
  ],
  "count": 1
}

where:

Name Type Description
id string user id provided by pawaPass
phoneNumbers array of objects details of phone numbers assigned to the user
phoneNumbers.verified bool whether this phone number is verified (by pawaPass or by you)
phoneNumbers.createdAt datetime when the phone number was assigned to the user
phoneNumbers.phoneNumber string phone number assigned to the user, in the E.164 format
externalUsers array of objects external users assigned to this pawaPass user (more than one entry means that this user might have multiple accounts in your system)
externalUsers.id string user id provided by you when creating the verification session
externalUsers.createdAt datetime when external user was assigned to this pawaPass user
updatedAt datetime user's update time
createdAt datetime user's creation time

You can narrow down the results using query parameters.

where:

  • phoneNumber (comma separated string) - phone number assigned to the user, in the E.164 format
  • externalUserId (comma separated uuid) - user id provided by you
  • id (comma separated uuid) - user id provided by pawaPass
  • isShareholder (boolean) - indicates to filter out only users who are or are not shareholders

Get user details

Get the details of a single user.

GET /users/:userId

Response

{
  "id": "79e38018-fb04-4e13-a6e3-e49834840d82",
  "updatedAt": "2023-03-31T13:10:28.193Z",
  "createdAt": "2023-03-31T13:09:37.076Z",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "2002-03-27",
  "estimatedAge": "over18",
  "image": "base64-encoded-image",
  "phoneNumbers": [
    {
      "phoneNumber": "+48717016015",
      "createdAt": "2023-04-03T11:30:37.616Z",
      "verified": true
    }
  ],
  "names": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "createdAt": "2023-04-03T11:30:37.616Z"
    }
  ],
  "documents": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "2002-03-27",
      "placeOfBirth": "Warsaw",
      "nationality": "Polish",
      "serialNo": "ID123456",
      "expiryAt": "2039-03-21",
      "issuedAt": "2029-03-21",
      "issuingAuthority": null,
      "placeOfIssue": null,
      "createdAt": "2023-04-03T11:30:37.663Z"
    }
  ],
  "externalUsers": [
    {
      "id": "your-user-id-1",
      "createdAt": "2023-04-03T11:30:37.663Z"
    }
  ]
}

where:

Name Type Description
id string user id provided by pawaPass
updatedAt datetime user's update time
createdAt datetime user's creation time
firstName string, optional user's first name (optional)
lastName string, optional user's last name (optional)
dateOfBirth string | null, optional user's date of birth (optional)
estimatedAge enum: unknown, under8, over8, over13, over16, over18, over21, over25, over30 estimated age with 99,5% confidence
image string base64 encoded user's image
names array of objects history of user's first and last names
names.firstName string firstName assigned to the user
names.lastName string lastName assigned to user
names.createdAt datetime when the first and last name were assigned to the user
phoneNumbers array of objects details of phone numbers assigned to user
phoneNumbers.verified bool whether this phone number is verified (by pawaPass or by you)
phoneNumbers.createdAt datetime when the phone number was assigned to the user
phoneNumbers.phoneNumber string phone number assigned to the user, in the E.164 format
documents array of objects details taken from the document's shown by the user
documents.firstName string user's firstName of the user from document
documents.lastName string user's lastName of the user from document
documents.dateOfBirth string user's date of birth from document
documents.placeOfBirth string user's place of birth from document
documents.nationality string user's nationality from document
documents.serialNo string user's document serial no
documents.expiryAt datetime user's document expiration date
documents.issuedAt datetime user's document obtained date
documents.issuingAuthority string authority which issued user's document
documents.placeOfIssue string place where user's document was issued
documents.createdAt datetime when the document was assigned to the user
externalUsers array of objects external users assigned to this pawaPass user (more than one entry means that this user might have multiple accounts in your system)
externalUsers.id string user id provided by you when creating the verification session
externalUsers.createdAt datetime when external user was assigned to this pawaPass user

Get linked users by device

Get all users which are linked to the same device as queried one.

GET /users/:userId/linked-by-device

Response

{
  "userId": "79e38018-fb04-4e13-a6e3-e49834840d82",
  "linkedUsersByDevice": [
    {
      "deviceId": "vskyslv2qq",
      "users": [
        {"userId":"79e38018-fb04-4e13-a6e3-e49834840d82"}
      ]
    },
    {
      "deviceId": "zrplxvbq7b",
      "users": [
        {"userId": "79e38018-fb04-4e13-a6e3-e49834840d82"},
        {"userId": "99c6e652-5c93-4aba-97ec-dde6905eda77"}
      ]
    }
  ]
}

where:

Name Type Description
userId string user identifier
linkedUsersByDevice object represents all devices linked to the queried user and all users linked to each device
linkedUsersByDevice.deviceId string unique device identifier
linkedUsersByDevice.users array list of users linked to the device, including the queried userId

Get share holder data

Get betPawa shares data for single user.

GET /users/:userId/shares

Response

{
  "isShareholder": true,
  "sharesNumber": 9
}

where:

Name Type Description
isShareholder boolean indicates whether the user is a shareholder or not
sharesNumber integer indicates how many shares the user owns

Batch create external user

Assign many external id to the user in pawaPass by phone numbers.

POST /users/external-users

Request body

{
    "externalUsers": [
      {
        "phoneNumber": "+48795236201",
        "externalUserId": "your-user-id-1-as-uuid"
      },
      {
        "phoneNumber": "+48790500480",
        "externalUserId": "your-user-id-1-as-uuid"
      },
      {
        "phoneNumber": "+48790500481",
        "externalUserId": "your-user-id-2-as-uuid"
      }
    ]
}
where:

Name Type Description
externalUserId uuid external user id from your system

Response

{
  "externalUsersWithSuccess": [
    {
      "externalUserId": "your-user-id-1-as-uuid",
      "phoneNumber": "+48795236201",
      "partnerUserId": "cbcca63b-4e99-467a-a88d-5cc275c928b1"
    }
  ],
  "unknownPhoneNumbers": [],
  "invalidPhoneNumbers": ["asd"],
  "duplicatedExternalUserIds": ["your-user-id-1-as-uuid"]
}
where:

Name Type Description
externalUsersWithSuccess array list of created external users
unknownPhoneNumbers array list of phone numbers that are unknown to us
invalidPhoneNumbers array list of invalid phone numbers
duplicatedExternalUserIds array list of already existing external user ids

List fingerprints with details for a user

Get a list of fingerprints related to a single user.

GET /users/:userId/fingerprints
GET /users/:userId/fingerprints?page=5&limit=20

Response

{
  "fingerprints": [
    {
      "id": "9e6cb90b-4d3a-4503-9174-de0b9f3baf77",
      "events": [
        {
          "id": "0decdc3b-985f-4d49-94ff-65109583704f",
          "data": {
            "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Mobile/15E148 Safari/604.1",
            "ipLocation": {
              "city": {
                "name": "Warsaw"
              }
            }
          }
        }
      ]
    }
  ],
  "count": 1
}

Note

fingerprints[].events[].data contains all data collected during fingerprinting process (above json is just an example)

List webhooks for a user

Get a list of webhooks related to a single user.

GET /users/:userId/webhooks
GET /users/:userId/webhooks?page=5&limit=20

Response

{
  "webhooks": [
    {
      "id": "9e6cb90b-4d3a-4503-9174-de0b9f3baf77",
      "userId": "85fcc4b4-e4f8-44a4-a101-7fa16ab5416c",
      "type": "user",
      "success": true,
      "payload": {
        "eventId": "2c84c97a-a76a-4881-9b6b-5a6b2fc7e8fc",
        "createdAt": "2023-03-27T11:49:43.967Z",
        "dataType": "user",
        "eventType": "user.created",
        "data": {
          "userId": "ab54e051-31aa-4ed5-8ea3-ed48e9d82937",
          "firstName": "John",
          "lastName": "Doe",
          "dateOfBirth": "2002-03-27",
          "createdAt": "2023-03-27T11:51:47.289Z",
          "estimatedAge": "over30",
          "phoneNumbers": [{
            "verified": true,
            "createdAt": "2023-03-27T11:51:47.289Z",
            "phoneNumber": "+48790500480"
          }],
          "names": [
            {
              "firstName": "John",
              "lastName": "Doe",
              "createdAt": "2023-03-27T11:51:47.289Z"
            }
          ],
          "externalUsers": [{
            "id": "your-user-id-1",
            "createdAt": "2023-03-27T11:51:47.289Z"
          }]
        }
      },
      "retryAt": null,
      "reason": "suspicious behavior",
      "updatedAt": "2023-03-31T13:10:28.193Z",
      "createdAt": "2023-03-31T13:09:37.076Z"
    }
  ],
  "count": 1
}
where:

Name Type Description
success bool whether the webhook was successfully delivered to your webhook endpoint
retryAt datetime when the next retry of the webhook's delivery is planned

Note

In case of retries, we will update the success, retryAt and updatedAt fields in an existing webhook rather than creating a new one.

Webhooks

We send events related to verifications and users using webhooks.

Info

Your provided webhook url needs to accept payloads from pawaPass. In case of problems with reaching your url (any non-200 response code), we will retry every 15 minutes.

Authorization

Info

To verify the authenticity of requests to your webhook endpoint, calculate the signature and compare it to the one in the X-SIGNATURE header. The signature is created using HMAC-SHA256 hash from the request body (as string) and the integration auth key.

JavaScript / ECMAScript

const signature = crypto.createHmac('sha256', authKey).update(Buffer.from(body, 'utf8')).digest('hex').toLowerCase();

Python

signature = hmac.new(authKey, msg=body, digestmod=hashlib.sha256).hexdigest().lower()

PHP

<?php $signature = strtolower(hash_hmac('sha256', $body, $authKey));

C# / .Net

var hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(authKey));
var hash = hmacsha256.ComputeHash(Encoding.UTF8.GetBytes(body));
var signature = Convert.ToHexString(hash).ToLower();

Base structure of the webhook

Each webhook consists of basic fields and the data field:

{
  "eventId": "2c84c97a-a76a-4881-9b6b-5a6b2fc7e8fc",
  "dataType": "user",
  "eventType": "user.updated",
  "createdAt": "2023-03-27T11:49:43.967Z",
  "data": {}
}
where:

Name Type Description
eventId uuid, string unique webhook id
dataType string, enum: user, verification, shareholder the type of object the webhook is related to
eventType string, enum: event-types-enums type of event that triggered the webhook
createdAt date webhook's creation time
data object the whole object related to the webhook (of type dataType)

DataType

Determines what type of data you can expect in the webhook's data field. There are three possible data types: user, verification and shareholder

Verification

Data contains information about a verification session.

{
  "eventId": "2c84c97a-a76a-4881-9b6b-5a6b2fc7e8fc",
  "dataType": "verification",
  "eventType": "verification.created",
  "createdAt": "2023-03-27T11:49:43.967Z",
  "data": {
    "verificationId": "85fcc4b4-e4f8-44a4-a101-7fa16ab5416c",
    "status": "created",
    "redirectUrl": "https://your-url.com?success=true",
    "errorRedirectUrl": "https://your-url.com?success=false",
    "externalUserId": "your-user-id-1-as-uuid",
    "phoneNumber": "+48790500480",
    "isPhoneNumberVerified": true,
    "phoneNumbers": [
      {
        "phoneNumber": "+48790500480",
        "isVerified": true
      },
      {
        "phoneNumber": "+48608504333",
        "isVerified": false
      }
    ],
    "firstName": "John",
    "lastName": "Doe",
    "requireFirstAndLastName": true,
    "requirements": [
      {
        "type": "firstAndLastName"
      },
      {
        "type": "dateOfBirth"
      },
      {
        "type": "document"
      }
    ],
    "collectedRequirements": [
      {
        "type": "firstAndLastName",
        "result": null,
        "verified": false
      },
      {
        "type": "dateOfBirth",
        "result": null,
        "verified": false
      },
      {
        "type": "document",
        "result": null,
        "verified": false
      }
    ],
    "userId": null,
    "reason": "suspicious behavior",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "validTo": "2023-03-27T12:19:43.960Z",
    "createdAt": "2023-03-27T11:49:43.959Z",
    "updatedAt": "2023-03-27T11:49:43.959Z"
  }
}
where:

Name Type Description
verificationId string verification session id
status string, enum: status-enum verification session status
redirectUrl string url to redirect to once verification session status changes to inReview, completed, or declined
externalUserId uuid user id provided by you
userId string, optional user id related to this verification, available only if status is completed
previousUserId string, optional previous user id related to this verification, available only if status is reverted
validTo datetime verification's expiration time
reason string verification's reason
metadata object, optional key-value data that you can attach to the verification, up to 50 keys, each with names up to 40 characters and values up to 500 characters.

Verification status

status describes the progress of verification

status when it is set possible transitions
created You created a new verification. started, closed, expired
started User clicked the verification link and opened the pawaPass web app. waitingForUserInput, inReview, completed, declined, closed, expired
waitingForUserInput User has successfully scanned their face, but still needs to provide some requested personal details (first and last name, date of birth) inReview, completed, declined, closed, expired
inReview User completed the verification, but needs to be reviewed manually. completed
completed User completed the verification without the need of manual review or was accepted after a review. `userId` field is available in the data object. In most cases, it is the final status. reverted
declined User didn't pass the verification (e.g. provided phone number is assigned to another user)
closed Verification was closed, usually due to a new verification being created for the same phone number. It is the final status.
expired Verification expired. The `validTo` field in the verification object indicates when verification is going to expire. It is the final status.
reverted Verification might be reverted in two cases:
* if our team in backward analysis detects any irregularities related to the user (e.g. new user was created instead of merge the user to existing one)
* if partner calls revert endpoint

User

Data contains information about the user (personal information and phone numbers).

{
  "eventId": "2c84c97a-a76a-4881-9b6b-5a6b2fc7e8fc",
  "dataType": "user",
  "eventType": "user.updated",
  "createdAt": "2023-03-27T11:49:43.967Z",
  "data": {
    "userId": "ab54e051-31aa-4ed5-8ea3-ed48e9d82937",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "2002-03-27",
    "createdAt": "2023-03-27T11:51:47.289Z",
    "estimatedAge": "over30",
    "phoneNumbers": [
      {
        "verified": true,
        "createdAt": "2023-03-27T11:51:47.289Z",
        "phoneNumber": "+48790500480"
      }
    ],
    "names": [
      {
        "firstName": "John",
        "last": "Doe",
        "createdAt": "2023-04-03T11:30:37.616Z"
      }
    ],
    "externalUsers": [
      {
        "id": "your-user-id-1",
        "createdAt": "2023-03-27T11:51:47.289Z"
      }
    ]
  }
}

where:

Name Type Description
userId string user id provided by pawaPass
createdAt datetime user's creation time
firstName string, optional user's first name (optional)
lastName string, optional user's last name (optional)
dateOfBirth string | null, optional user's date of birth (optional)
estimatedAge enum: unknown, under8, over8, over13, over16, over18, over21, over25, over30 estimated age with 99,5% confidence
names array of objects history of user's first and last names
names.firstName string firstName assigned to the user
names.lastName string lastName assigned to user
names.createdAt datetime when the first and last name were assigned to the user
phoneNumbers array of objects details of phone numbers assigned to user
phoneNumbers.verified bool whether this phone number is verified (by pawaPass or by you)
phoneNumbers.createdAt datetime when the phone number was assigned to the user
phoneNumbers.phoneNumber string phone number assigned to the user, in the E.164 format
externalUsers array of objects external users assigned to this pawaPass user (more than one entry means that this user might have multiple accounts in your system)
externalUsers.id string user id provided by you when creating the verification session
externalUsers.createdAt datetime when external user was assigned to this pawaPass user

Shareholder

Data contains information about the shareholder. Webhook will be sent every time when verification for user is completed and user is verified as shareholder.

{
  "eventId": "2c84c97a-a76a-4881-9b6b-5a6b2fc7e8fc",
  "dataType": "shareholder",
  "eventType": "shareholder.verified",
  "createdAt": "2023-03-27T11:49:43.967Z",
  "data": {
    "userId": "ab54e051-31aa-4ed5-8ea3-ed48e9d82937",
    "isShareholder": true,
    "externalUserIds": ["your-user-id-1-as-uuid", "your-user-id-2-as-uuid"]
  }
}
Name Type Description
userId string user id provided by pawaPass
isShareholder boolean (always: true) verified user is shareholder
externalUserIds array of strings external users assigned to pawaPass user

EventType

dataType eventType When it is triggered
verification verification.created you created a new verification
verification.updated verification was updated (its status changed)
user user.created new user account was created
user.merged user was merged with an existing user account
user.updated user data was updated (e.g. new phone number added, phone number verified, personal data updated)
user.deleted user data was deleted (note! if you still need any data from the user then start verification once again)
shareholder shareholder.verified user has been verified as shareholder

Example workflows

Create a new user

activity webhooks (eventType)
You create a new verification and pass its url to the end-user. verification.created
User clicks the link and starts the verification in the pawaPass web app. Phone number is automatically set based on the url. verification.updated
User successfully completes the verification. We create a new user account in pawaPass. verification.updated
user.created
User enters their first and last name. user.updated
User verifies their phone number. user.updated

Merge the user with an existing one

activity webhooks (eventType)
You create a new verification and pass its url to the end-user. verification.created
User clicks the link and starts the verification in the pawaPass web app. Phone number is automatically set based on the url. verification.updated
User successfully completes the verification. Based on the face model, we detect that this user already exists in pawaPass. We add the new data to their existing account. verification.updated
user.merged

User in manual review

activity webhooks (eventType)
You create a new verification and pass its url to the end-user. verification.created
User clicks the link and starts the verification in the pawaPass web app. Phone number is automatically set based on the url. verification.updated
User completes the verification, but a manual review is needed (mostly because of potentially conflicting data). verification.updated
During the review, a pawaPass agent decides to create a new account for the user verification.updated
user.created