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:

Name	Type	Description
`type`	enum: [firstAndLastName, dateOfBirth, document, phoneNumbers]	requested data type
`result`	object \| null	object with collected data (see example above), might be null if no data collected
`verified`	boolean (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

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.
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

Only successfully completed verification (status: completed) might be reverted. Otherwise, the endpoint returns 409 Conflict status code with an appropriate error message.
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).
User will be deleted (and user.deleted webhook will be sent) if no more externalUserId is linked to the user.
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": {
            "objects": [
              {
                "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": {
        "objects": [
          {
            "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": {
                "objects": [
                  {
                    "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 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	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

Base url¶

Access¶

Authorization¶

Pagination¶

Endpoints¶

Get partner details¶

Response¶

Update partner details¶

Request body¶

Response¶

List auth keys¶

Response¶

Create a new auth key¶

Request body¶

Response¶

Create a new verification session¶

Request body¶

Response¶

Revert completed verification¶

Request body¶

Response¶

List verifications¶

Response¶

Get verification details¶

Response¶

Get user activities in verification¶

Response¶

Get linked verifications by device¶

Response¶

List webhooks for a verification¶

Response¶

List users¶

Response¶

Get user details¶

Response¶

Get linked users by device¶

Response¶

Get share holder data¶

Response¶

Batch create external user¶

Request body¶

Response¶

List fingerprints with details for a user¶

Response¶

List webhooks for a user¶

Response¶

Webhooks¶

Authorization¶

JavaScript / ECMAScript¶

Python¶

PHP¶

C# / .Net¶

Base structure of the webhook¶

DataType¶

Verification¶

Verification status¶

User¶

Shareholder¶

EventType¶

Example workflows¶

Create a new user¶

Merge the user with an existing one¶

User in manual review¶