curl

curl -X POST "https://api.services.payward.com/v1/users/AA45N8G4MLDYWAR7/verifications/url" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity_document",
    "metadata": {
      "identity": {
        "full_name": {
          "first_name": "Alex",
          "last_name": "Morgan"
        },
        "birth": {
          "date": "2023-03-13"
        }
      },
      "document_type": "passport",
      "document_number": "A1234567",
      "issuing_country": "AD",
      "verifier": "example",
      "verified_at": "2023-03-13T12:34:56Z",
      "verifier_response": {
        "status": "approved"
      }
    },
    "front_url": "https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256"
  }'

{
  "data": {
    "verification_id": "ver_01J0M9P2T7K3W2BHJ7T9"
  }
}

Verifications

Submit Verification from URL

Submit a verification for a user with documents provided via presigned URLs.

This endpoint is useful when documents are already stored in a cloud storage provider (e.g. AWS S3, Google Cloud Storage) and accepts identity document, residence document, and selfie verification payloads.

A verification is a check performed on a user to verify information provided by the user, typically by a third party such as an identity verification provider. Checks are most commonly performed on documents, such as a passport or driver’s license, but can also include sanctions or Politically Exposed Person (PEP) checks.

URL and file requirements

URLs must be HTTPS URLs on allowlisted domains, up to 4096 characters. Each redirect target must also use HTTPS and an allowlisted domain. The server follows up to three redirects.

The server extracts the decoded filename from the submitted URL path. The filename must be 255 bytes or less, cannot be . or .., and cannot contain path separators or control characters. It must include an extension matching the detected file content.

Downloaded files can be up to 150 MiB (157286400 bytes). The size limit is enforced from the Content-Length header and while streaming the response body. Accepted file types are JPEG/JPG, PNG, PDF, MP4/M4V, WebM, and MOV/QuickTime. Passport identity document submissions must omit back_url. If verifier_response_url is provided, that file is used as raw verifier response evidence instead of metadata.verifier_response.

metadata.verified_at must be a valid date-time. Invalid values are rejected instead of being replaced with the submission time. If file upload or final verification submission fails, files uploaded for that request are discarded.

Domain allowlisting

For security, the domains you use for presigned URLs must be allowlisted before you can use this endpoint. Contact your account manager to configure the allowed domains for your integration.

POST

users

{user_id}

verifications

url

curl

curl -X POST "https://api.services.payward.com/v1/users/AA45N8G4MLDYWAR7/verifications/url" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity_document",
    "metadata": {
      "identity": {
        "full_name": {
          "first_name": "Alex",
          "last_name": "Morgan"
        },
        "birth": {
          "date": "2023-03-13"
        }
      },
      "document_type": "passport",
      "document_number": "A1234567",
      "issuing_country": "AD",
      "verifier": "example",
      "verified_at": "2023-03-13T12:34:56Z",
      "verifier_response": {
        "status": "approved"
      }
    },
    "front_url": "https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256"
  }'

{
  "data": {
    "verification_id": "ver_01J0M9P2T7K3W2BHJ7T9"
  }
}

Authorizations

API-Key

string

header

required

Your public API key. Identifies the partner making the request.

API-Nonce

string

header

required

Monotonically increasing nonce included in the request signature.

API-Sign

string

header

required

HMAC signature over the request, computed with your private key.

Path Parameters

user_id

string

required

ID of the user the request applies to. For partners operating in the B2B2C model, this is the Sub-User the request is acting on behalf of. Canonical identifier for a user in the Payward public API.

Required string length: 14 - 42

Body

application/json

Option 1
Option 2
Option 3

type

enum<string>

required

Available options:

identity_document

metadata

object

required

Metadata about the verification.

Show child attributes

front_url

string<uri>

required

Presigned URL to the front side of the identity document. The filename is extracted from the URL path and must meet the URL and file requirements.

Required string length: 1 - 4096

back_url

string<uri> | null

Presigned URL to the back side of the identity document (optional). The filename is extracted from the URL path and must meet the URL and file requirements. Passport submissions must omit this field.

Required string length: 1 - 4096

verifier_response_url

string<uri> | null

Presigned URL to the verifier response document (optional). The filename is extracted from the URL path and must meet the URL and file requirements. If provided, this file is used as the raw verifier response evidence instead of metadata.verifier_response.

Required string length: 1 - 4096

Response

data

object

required

Show child attributes

Get quote List Webhooks

⌘I