Identities & Compliance

An identity is a core object in our API, representing the fundamental information required for any individual or business to interact with partner financial institutions (PFIs) via the Borderless network. All transactions, payment instructions, and accounts are associated with an identity. All identities must pass a compliance check before they are allowed to do any transactions in the network. The compliance check can be performed by you or the (PFI), depending on the compliance model that the PFI supports. You can find more detailed information in the compliance section below.

If you’re just getting started, please check out our quick start guide.

Identity types

There are two types of identities in the Borderless network: Personal — used to represent a person. Can usually start doing transactions on the Borderless network in minutes. You can find detailed instructions on how to create them and get them ready in the Personal Identity tab below. Business — used to represent a business or corporation. Can usually start doing transactions on the Borderless network in three to five business days. You can find detailed instructions on how to create these identities and get them ready in the Business Identity tab below.

Compliance details

Each Partner Financial Institution (PFI) on the Borderless network has its own compliance programs, and decides how to implement them. The Borderless network is a data layer that stores the information for every person or business doing transactions, and sends it on to the PFIs for their usual operations and record keeping. You only upload the necessary data to the Borderless identity once, then it is available for all the PFIs in the network. This is is part of a process called compliance orchestration. In some cases, passing one compliance-check will automatically satisfy other checks with less strict requirements. This is handled via the incorporates field: [slug-1, slug-2] This means that upon passing this compliance-check, the identity also gains access to the operation options covered by the checks listed in incorporates.

Working with identities & compliance

Note: Borderless is never in the flow of funds, and never takes custody of client or partner funds. Borderless is a gateway connecting clients directly with regulated and licensed providers.

Personal Identity
Business Identity

Create a personal identity

Creating a personal identity is an important step when using the Borderless network. Every deposit or withdrawal must be tied to an identity, and this is also how we collect information for required compliance checks (KYC).

Step 1: Initiate identity object

First, initiate an identity object, which creates a simple identity object. We will then add information to this object so that we can use it for KYC or KYB going forward. You can find a link to the endpoint reference documentation, as well as request and response examples below.This compliance process is managed by our partner finanical institutions (PFIs) who are the locally licensed and regulated stablecoin and fiat on-ramps and off-ramps.Some requests require an Idempotency-Key header to ensure that operations are not accidentally executed multiple times. Please generate and use a unique UUID for this field.

Please capture identity id from the response to use it during account creation later.

Endpoint: POST /identities/personal

curl -X POST "https://sandbox-api.borderless.xyz/v1/identities/personal" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
     -d '{
  		"firstName": "John",
  		"lastName": "Doe",
  		"secondLastName": "Smith",
  		"middleName": "Michael",
  		"taxId": "123456789",
  		"dateOfBirth": "2003-01-01",
  		"email": "john.doe@example.com",
  		"phone": "+1234567890",
  		"activity": "Software Engineer",
  		"sex": "Male",
  		"occupationCode": "172011",
  		"employmentStatus": "SelfEmployed",
  		"sourceOfFunds": "InvestmentsLoans",
  		"accountPurpose": "InvestmentPurposes",
  		"accountPurposeOther": "string",
  		"monthlyAmounts": "From10KTo50K",
  		"actingAsIntermediary": false,
  		"address": {
   		 	"street1": "123 Main St",
    		"street2": "Apt 4B",
    		"city": "New York",
    		"state": "NY",
    		"country": "US",
    		"postalCode": "10001"
  			}
		}
		'

Step 2: Gather configured PFIs

Once an identity has been created, this identity will have limited ability to transact until they pass a KYC or KYB check with the on-ramp and off-ramp providers (PFIs) they’d like to enable. You can easily gather the configured PFIs from our API before collecting the necessary documents and initiating a compliance check.Additionally, this endpoint provides the terms of service link, where required, which will need to be forwarded to the client. Some of our partner financial institutions (PFIs) require users to accept their terms and conditions before they can transact. Each identity must accept their own ToS link, and it cannot be reused.

Please capture compliance slug from the response to use it next.

Please capture terms of service link to deliver to end users.

Endpoint: GET /identities/{identityId}/compliance-checks

curl -X GET "https://sandbox-api.borderless.xyz/v1/identities/{identityId}/compliance-checks" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -d '{
            "country": "AF",
            "asset": "USDC_BASE",
            "fiat": "USD", 
            "paymentMethod": "ACH",
            "type": "Deposit"
         }'

Step 3: Check required documents

With the identity id and compliance slug you can now check the list of required information and documentation needed for the configured PFIs. This allows you to dynamically build your UI such that you only ask your customers for what is required for each specific business or user.

Please use the compliance slug from the response above.

Endpoint: GET /identities/{identityId}/compliance-checks/{slug}/requirements

curl -X GET "https://sandbox-api.borderless.xyz/v1/identities/{identityId}/compliance-checks/{slug}/requirements" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \

Step 4: Attach required documents

Now that required documents have been identified, and the terms of service link, if required, has been accepted, we can submit these documents for review via our API. This information will be added to the identity object so that we can streamline and orchestrate future compliance as well.For clarity, the id parameter here is the identity id of the organization or person you have created in step 1 of this process. This will submit all required information for the compliance check. You can use this endpoint at any time to add documents to the related identity object.

Please note, imageFront and imageBack should be converted in base64 format with resolution at least 200*200pixels.

Endpoint: PUT /identities/{id}/documents

curl -X PUT "https://sandbox-api.borderless.xyz/v1/identities/{id}/documents" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
     -d '{
            "issuingCountry": "US",
            "type": "Passport",
            "issuedDate": "2024-07-25",
            "expiryDate": "2027-07-25",
            "imageFront": "image/200*200;base64",
            "imageBack": "image/200*200;base64"
         }'

Step 5: Start compliance check

After attaching the required documents to the identity object, you are ready to submit and start the compliance check with our partner financial institutions (PFIs). You can submit this once, and we will orchestrate the data to all PFIs you have enabled, helping to streamline an otherwise repetitive process.If all prerequisites are satisfied, the check will begin. Use the GET request above from step 2 and the API will return the current compliance status.

Endpoint: POST /identities/{identityId}/compliance-checks/{slug}

curl -X POST "https://sandbox-api.borderless.xyz/v1/identities/{identityId}/compliance-checks/{slug}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\

The timeline for different levels of compliance checks varries. It can be as fast as near-instant and in some rare occasions can take a few days. We will keep you informed through the whole process via the returned compliance status in the response body of step 2.

Requests for information (RFIs) are a regular part of the compliance process. If there are follow up questions on documents, completely missing documents, or other details that need to be reviewed manually, our PFIs can send a request for additional information.
These requests for information will be communicated manually, and are generally expected to be resolved in 24 to 48 hours.

Create a business identity

Creating a business identity is an important step when using the Borderless network. Every deposit or withdrawal must be tied to an identity, and this is also how we collect information for required compliance checks (KYB).

Step 1: Initiate identity object

We need to collect information about the people who own, control, and can sign for the business.
It doesn’t have to be just one person, different people can cover these roles, but all roles must be represented.For a person to be considered an owner of the business, they need to own at least 25% of it (directly or indirectly). They are called Ultimate Beneficial Owners (UBOs). Each business must list all of its UBOs. Persons that control, and can sign for the business do not have to be UBOs.You need a personal identity for each person that is either an owner, has control, or can sign for the business. If you have not yet created one, please click on the Personal Identity tab at the top of this section. After creating their identity, you will obtain an identityId for each person. You will use the identityId in future steps to create a business identity.

Please capture identity id from the response to use it during account creation later.

Endpoint: POST /identities/business

curl -X POST "https://sandbox-api.borderless.xyz/v1/identities/business" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
     -d '{
  		"email": "business@example.com",
  		"phone": "+1234567890",
  		"taxId": "123456789",
  		"name": "Example Corp",
  		"dateOfIncorporation": "2003-01-01",
  		"address": {
    		"street1": "123 Main St",
    		"street2": "Apt 4B",
    		"city": "New York",
    		"state": "NY",
    		"country": "US",
    		"postalCode": "10001"
  		},
  		"description": "A technology solutions provider",
  		"sourceOfFunds": "inter_company_funds",
  		"businessIndustryCode": "336390",
  		"website": "https://example.com",
  		"businessType": "Llc",
  		"isDao": false,
  		"hasMaterialIntermediaryOwnership": false,
  		"businessTradeName": "Example Solutions",
  		"accountPurpose": "investment_purposes",
  		"accountPurposeOther": "string",
  		"ultimateBeneficialOwners": [
    		{
      		"hasOwnership": true,
      		"hasControl": true,
      		"controlPersonTitle": "CEO",
      		"ownershipPercentage": 30,
      		"isSigner": true,
      		"relationshipEstablishedAt": "2023-01-15",
      		"personalIdentityId": "cm9db4g2s4r7ro224ra6u1qvl"
    		},
    		{
      		"hasOwnership": true,
      		"hasControl": true,
      		"controlPersonTitle": "CEO",
      		"ownershipPercentage": 30,
      		"isSigner": true,
      		"relationshipEstablishedAt": "2023-01-15",
      		"personalIdentity": {
        		"firstName": "John",
        		"lastName": "Doe",
        		"secondLastName": "Smith",
        		"middleName": "Michael",
        		"taxId": "123456789",
        		"dateOfBirth": "2003-01-01",
        		"email": "john.doe@example.com",
        		"phone": "+1234567890",
        		"activity": "Software Engineer",
        		"sex": "Male",
        		"occupationCode": "172011",
        		"employmentStatus": "SelfEmployed",
        		"sourceOfFunds": "InvestmentsLoans",
        		"accountPurpose": "InvestmentPurposes",
        		"accountPurposeOther": "string",
        		"monthlyAmounts": "From10KTo50K",
        		"actingAsIntermediary": false,
        		"address": {
          			"street1": "123 Main St",
          			"street2": "Apt 4B",
          			"city": "New York",
          			"state": "NY",
          			"country": "US",
          			"postalCode": "10001"
        			}
      			}
    		 }
  		  ]
		}
		'

Step 2: Gather configured PFIs

Please capture compliance slug from the response to use it next.

Please capture terms of service link to deliver to end users.

Endpoint: GET /identities/{identityId}/compliance-checks

curl -X GET "https://sandbox-api.borderless.xyz/v1/identities/{identityId}/compliance-checks" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -d '{
            "country": "AF",
            "asset": "USDC_BASE",
            "fiat": "USD", 
            "paymentMethod": "ACH",
            "type": "Deposit"
         }'

Step 3: Check required documents

Please use the compliance slug from the response above.

Endpoint: GET /identities/{identityId}/compliance-checks/{slug}/requirements

curl -X GET "https://sandbox-api.borderless.xyz/v1/identities/{identityId}/compliance-checks/{slug}/requirements" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \

Step 4: Attach required documents

Please note, imageFront and imageBack should be converted in base64 format with resolution at least 200*200pixels.

Endpoint: PUT /identities/{id}/documents

curl -X PUT "https://sandbox-api.borderless.xyz/v1/identities/{id}/documents" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
     -d '{
            "issuingCountry": "US",
            "type": "Passport",
            "issuedDate": "2024-07-25",
            "expiryDate": "2027-07-25",
            "imageFront": "image/200*200;base64",
            "imageBack": "image/200*200;base64"
         }'

Step 5: Start compliance check

Endpoint: POST /identities/{identityId}/compliance-checks/{slug}

curl -X POST "https://sandbox-api.borderless.xyz/v1/identities/{identityId}/compliance-checks/{slug}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\

Handle compliance rejection

The rejectionReasons field in the IdentityComplianceCheck API response provides structured information about why a compliance check was rejected by Payment Facilitator Institutions (PFIs).

Response Structure

Each rejection reason object contains three fields:

code (enum: ComplianceRejectionReasonCode): A standardized enum value categorizing the rejection reason
description (string): A predefined, human-readable message corresponding to the code
pfiMessage (string): The raw, original message from the underlying verification provider

Example Response

{
  "rejectionReasons": [
    {
      "code": "DocumentExpired",
      "description": "Document has expired.",
      "pfiMessage": "ID is expired."
    },
    {
      "code": "FaceNotLive",
      "description": "Liveness check failed.",
      "pfiMessage": "The selfie video shows signs of presentation attack."
    }
  ]
}

Rejection Reason Codes Reference

Document Quality & Detection

Code	Message	Description
`DocumentNotFound`	Document not found.	No government-issued identity document was detected in the submission.
`DocumentUnrecognized`	Document could not be recognized.	The document type or format could not be identified by the verification system.
`DocumentUnreadable`	Document image is unreadable.	The document image quality prevents extraction of information.
`DocumentExpired`	Document has expired.	The expiration date on the document has passed.
`DocumentDamaged`	Document is damaged.	Physical damage to the document prevents proper verification.
`DocumentCropped`	Document image is cropped.	The document image is cut off or incomplete.
`DocumentIncomplete`	Document submission is incomplete.	Required document pages or sides are missing.
`DocumentBlurry`	Document image is blurry.	Motion blur or focus issues prevent clear reading of the document.
`DocumentPoorQuality`	Document image quality is too low.	Resolution or compression artifacts make the document unusable.
`DocumentGlareDetected`	Glare detected on document.	Light reflection obscures parts of the document.
`DocumentTooSmall`	Document image is too small.	The document appears too small in the frame to extract details.
`DocumentTooFar`	Document is too far from the camera.	Distance from camera prevents reading document details.
`DocumentFaceNotFound`	Face not found on document.	Photo on the identity document could not be detected.
`DocumentFrontMissing`	Front side of document is missing.	The front page of the document was not submitted.
`DocumentBackMissing`	Back side of document is missing.	The back page of the document was not submitted.
`DocumentFrontBackMismatch`	Front and back document details do not match.	Information on front and back pages is inconsistent.
`DocumentSameSideSubmitted`	Same side of the document was submitted twice.	Both submissions show the same side of the document.
`DocumentWrongType`	Incorrect document type submitted.	The submitted document type doesn’t meet requirements.
`DocumentNotAccepted`	Document type is not accepted.	This specific document type is not supported.
`DocumentInvalidDates`	Document dates are invalid.	Issue date, expiry date, or other dates are logically invalid.

Document Fraud & Tampering

Code	Message	Description
`FraudDocumentTampered`	Document appears tampered.	Signs of physical alteration detected on the document.
`FraudDocumentAltered`	Document appears altered.	Document information has been modified.
`FraudDocumentFake`	Document appears fake.	Document does not match characteristics of genuine documents.
`FraudDocumentForged`	Document appears forged.	Document appears to be a counterfeit.
`FraudDocumentCompromised`	Document security appears compromised.	Security features of the document have been breached.
`FraudDocumentPhotoOfPhoto`	Document seems to be a photo of a photo.	The submission is a photograph of a physical document rather than the original.
`FraudDocumentScreenDetected`	Document was captured from a screen.	The document was photographed from a digital display.
`FraudDocumentElectronicReplica`	Document appears to be an electronic replica.	A digital copy rather than the physical document was submitted.
`FraudDocumentPrintout`	Document appears to be a printout.	Document is a printed copy rather than an original.
`FraudDocumentPaperCopy`	Document appears to be a paper copy.	Document is a photocopied or scanned reproduction.
`FraudDocumentBlackWhite`	Black and white document copy detected.	Document lacks color, suggesting it’s a copy.
`FraudDocumentFoundOnline`	Document image was found online.	The submitted image matches images available on the internet.
`FraudDocumentArtificialImage`	Document appears AI-generated.	Image shows signs of artificial intelligence generation.
`FraudDocumentArtificialText`	Document contains AI-generated text.	Text on the document appears synthetically generated.
`FraudDocumentTextForgery`	Document text appears forged.	Text appears to be manually altered or falsified.
`FraudDocumentFeatureVerificationFailed`	Document security features failed verification.	Holograms, watermarks, or other security features are absent or incorrect.
`FraudDocumentCheckDigitFailed`	Document check digits failed validation.	Mathematical verification of document numbers failed.
`FraudDocumentFabrication`	Document appears fabricated.	Document appears to be completely manufactured rather than issued.

Document Data & MRZ

Code	Message	Description
`DocumentDataMissingField`	Document data is missing a required field.	A required data field could not be extracted from the document.
`DocumentDataMissingExpiry`	Document expiry date is missing.	The expiration date is not present or readable.
`DocumentDataMissingIssueDate`	Document issue date is missing.	The issuance date is not present or readable.
`DocumentDataMissingDateOfBirth`	Date of birth is missing on the document.	Birth date field is absent or unreadable.
`DocumentDataMissingNumber`	Document number is missing.	The primary document identifier is absent or unreadable.
`DocumentDataMissingPersonalNumber`	Personal number is missing on the document.	National ID or personal number is absent or unreadable.
`DocumentDataMissingName`	Name is missing on the document.	The holder’s name is absent or unreadable.
`DocumentDataMissingAddress`	Address is missing on the document.	Address information is absent or unreadable.
`DocumentDataMissingDetails`	Additional document details are missing.	Other required fields could not be extracted.
`DocumentDataInvalidDetails`	Document details appear invalid.	Extracted information contains invalid or illogical values.
`DocumentDataMachineReadableZoneNotDetected`	Machine-readable zone was not detected.	The MRZ on passports or IDs could not be located.
`DocumentDataMachineReadableZoneMismatch`	Machine-readable zone data does not match.	MRZ data conflicts with visual inspection zone data.
`DocumentDataMachineReadableZoneInconsistent`	Machine-readable zone data is inconsistent.	MRZ contains internal contradictions or errors.
`DocumentDataBarcodeMissing`	Document barcode is missing.	Required barcode (e.g., PDF417) is absent or unreadable.
`DocumentDataBarcodeInconsistent`	Document barcode data is inconsistent.	Barcode data conflicts with other document information.

Identity Verification

Code	Message	Description
`IdentityVerificationFailed`	Identity verification failed.	General failure to verify the identity against authoritative sources.
`IdentityCannotVerify`	Identity could not be verified.	Unable to confirm identity through available verification methods.
`IdentityNameMismatch`	Identity name does not match records.	Name on document doesn’t match provided or database records.
`IdentityDateOfBirthMismatch`	Date of birth does not match records.	Birth date conflicts with provided or database information.
`IdentityDataMismatch`	Identity data does not match records.	General mismatch between document and records.
`IdentityTypeMismatch`	Identity type does not meet requirements.	The type of identity provided doesn’t satisfy requirements.
`IdentityCountryMismatch`	Identity country does not meet requirements.	Document country differs from expected or required country.
`IdentityNumberInvalid`	Identity number is invalid.	The identity/document number format is incorrect or fails validation.
`IdentityNumberNotVerified`	Identity number could not be verified.	Unable to confirm identity number against government databases.
`IdentityNumberFormatInconsistent`	Identity number format is inconsistent.	The number format doesn’t match the expected pattern for that document type.
`IdentityFormatInconsistent`	Identity format is inconsistent.	Overall document format doesn’t match standard specifications.
`IdentityExtractionInconsistent`	Extracted identity data is inconsistent.	Extracted data contains internal contradictions.
`IdentityDetailsInconsistent`	Identity details are inconsistent.	Information fields contradict each other or known facts.
`IdentityPreviousSubmissionInconsistent`	Identity details conflict with a previous submission.	Current submission contradicts a prior verification attempt.
`IdentityPreviouslySeen`	Identity document was previously seen.	This exact document has been submitted before.
`IdentityPreviouslyAttempted`	Identity verification was previously attempted.	Prior verification attempts exist for this identity.
`IdentityDuplicateAccount`	Duplicate account detected for this identity.	This identity is already associated with another account.
`IdentityDuplicateSubmission`	Duplicate identity submission detected.	The same identity was recently submitted.
`IdentityNotRealId`	Submitted ID does not appear genuine.	Document fails authenticity checks.
`IdentityUnderAge`	Individual is under the required age.	Person doesn’t meet minimum age requirements.
`IdentityMinor`	Individual is a minor.	Person is below the age of majority.
`IdentityCannotValidateAge`	Unable to validate the individual’s age.	Age verification cannot be completed with available information.
`IdentityAgeMismatch`	Age does not match provided information.	Calculated age conflicts with stated or expected age.
`IdentityDeceased`	Individual appears as deceased in records.	Identity matches records of deceased individuals.
`IdentitySuspectedTheft`	Identity is suspected to be stolen.	Identity characteristics suggest it may be fraudulently obtained.

Biometric & Face

Code	Message	Description
`FaceNotFound`	Face not found.	No face was detected in the selfie or video submission.
`FaceMultipleDetected`	Multiple faces detected.	More than one face appears in the submission.
`FaceMismatch`	Face does not match the document.	Selfie face doesn’t match the document photo.
`FaceLowSimilarity`	Face similarity is too low.	Biometric comparison score is below acceptance threshold.
`FaceIdentical`	Face matches another submission.	Face is identical to a different person’s submission.
`FacePhotoMismatch`	Selfie does not match the document photo.	Live photo differs from document photo.
`FacePublicFigure`	Face matches a public figure.	The person appears to be impersonating a celebrity or public figure.
`FaceNotLive`	Liveness check failed.	Unable to confirm the subject is physically present.
`FaceLivenessFailed`	Liveness detection failed.	Signs of spoofing detected (mask, photo, video replay).
`FaceLivenessReviewRequired`	Liveness check requires manual review.	Automated liveness check was inconclusive.
`FaceLivenessTooFar`	Face is too far for liveness check.	Distance prevents accurate liveness detection.
`FacePhotoOfPhoto`	Detected face appears to be a photo of a photo.	Selfie shows characteristics of photographed images.
`FaceCovered`	Face is covered.	Mask, glasses, or other objects obscure facial features.
`FaceEdited`	Face image appears edited.	Digital manipulation detected in facial image.
`FaceBlur`	Face image is blurred.	Motion or focus blur affects facial features.
`FaceBlurry`	Face image is blurry.	Image quality prevents accurate facial recognition.
`FaceTooClose`	Face is too close to the camera.	Face fills too much of the frame for proper analysis.
`FaceTooFar`	Face is too far from the camera.	Face is too small in the frame for biometric matching.
`FaceCropped`	Face is cropped in the image.	Part of the face is cut off in the submission.
`FaceTooSmall`	Face is too small in the image.	Facial resolution is insufficient for matching.
`FaceAngleTooLarge`	Face angle is too large.	Face is at an extreme angle preventing clear biometric capture.
`FaceDeepfake`	Face appears to be a deepfake.	AI-generated or manipulated face detected.
`FaceVideoFraud`	Face appears manipulated in video.	Video liveness check shows signs of digital manipulation.
`FacePreviouslyOnboarded`	Face was previously onboarded.	This face biometric is already registered in the system.

Address Verification

Code	Message	Description
`AddressMissing`	Address was not provided.	No address information was submitted.
`AddressIncomplete`	Address information is incomplete.	Required address fields are missing.
`AddressMismatch`	Address does not match records.	Provided address conflicts with verification data.
`AddressNotVerified`	Address could not be verified.	Unable to confirm address through available sources.
`AddressPoBox`	PO boxes are not accepted.	Post office boxes are not valid for this verification.
`AddressProofMissing`	Proof of address is missing.	Required address documentation was not provided.
`AddressProofInvalid`	Proof of address is invalid.	Submitted proof of address doesn’t meet requirements.
`AddressProofExpired`	Proof of address has expired.	The proof of address document is too old.
`AddressProofNotRecent`	Proof of address is not recent enough.	Document date doesn’t meet recency requirements.
`AddressDocumentUnrecognized`	Address document could not be recognized.	The type of address proof submitted is not recognized.
`AddressDocumentMissingAddress`	Address document is missing the address.	Address field is not present on the submitted proof.
`AddressDocumentMissingName`	Address document is missing the name.	Name field is not present on the address proof.
`AddressDocumentMissingIssueDate`	Address document is missing the issue date.	Date of issuance is absent on the address proof.
`AddressDocumentNameMismatch`	Name on the address document does not match.	Name on address proof differs from identity document.
`AddressDocumentAddressMismatch`	Address on the document does not match.	Address on proof differs from stated address.

Geographic Restrictions

Code	Message	Description
`GeographicRestrictedRegion`	Region is restricted.	The geographic region is not supported for compliance reasons.
`GeographicDisallowedCountry`	Country is disallowed.	Services are not available in this country.
`GeographicUnsupportedCountry`	Country is not supported.	Country is outside the service area.
`GeographicProhibitedCountry`	Country is prohibited.	Country is explicitly restricted due to regulations.
`GeographicProhibitedState`	State or province is prohibited.	Specific state/province is restricted.
`GeographicUnsupportedState`	State or province is not supported.	Service not available in this state/province.
`GeographicUnsupportedRegion`	Region is not supported.	Geographic region is outside coverage area.
`GeographicLocationMismatch`	Geolocation does not match provided information.	IP or GPS location conflicts with stated location.
`GeographicHighRiskJurisdiction`	High-risk jurisdiction detected.	Country/region is flagged as high-risk for financial crime.

Compliance & AML

Code	Message	Description
`ComplianceAmlMatch`	Match found on AML lists.	Individual appears on Anti-Money Laundering watchlists.
`ComplianceAmlFailed`	AML screening failed.	Unable to pass Anti-Money Laundering checks.
`CompliancePepMatch`	Match found on PEP lists.	Individual identified as a Politically Exposed Person.
`CompliancePotentialPep`	Potential PEP match detected.	Possible match to Politically Exposed Person lists.
`ComplianceSanctionsMatch`	Match found on sanctions lists.	Individual appears on international sanctions lists.
`ComplianceWatchlistMatch`	Match found on watchlists.	Match detected on regulatory or internal watchlists.
`ComplianceAdverseMedia`	Adverse media detected.	Negative news coverage or media reports found.
`ComplianceBackgroundCheckAlert`	Background check returned alerts.	Background screening identified potential issues.
`ComplianceOccupationRestricted`	Occupation is restricted.	Stated occupation is not permitted.
`ComplianceIndustryRestricted`	Industry is restricted.	Industry sector is not supported.
`ComplianceSourceOfFunds`	Source of funds requires review.	Source of funds needs additional verification.
`ComplianceElderAbuse`	Potential elder abuse risk detected.	Indicators suggest possible financial exploitation.

Information Completeness

Code	Message	Description
`InformationMissingField`	A required information field is missing.	Essential field was not provided in submission.
`InformationIncomplete`	Provided information is incomplete.	Submission lacks required information.
`InformationInconsistent`	Provided information is inconsistent.	Submitted information contains contradictions.
`InformationInvalidTaxId`	Tax ID is invalid.	Tax identification number format or value is incorrect.
`InformationContactInvalid`	Contact information is invalid.	Phone or email format is incorrect.
`InformationEmailInvalid`	Email address is invalid.	Email format is incorrect or undeliverable.
`InformationEmailNotFound`	Email address was not found.	Email address doesn’t exist in verification databases.
`InformationEmailMismatch`	Email address does not match records.	Email differs from expected or previous records.
`InformationPhoneInvalid`	Phone number is invalid.	Phone number format or country code is incorrect.
`InformationPhoneNotFound`	Phone number was not found.	Phone number doesn’t exist in verification databases.
`InformationPhoneMismatch`	Phone number does not match records.	Phone differs from expected or previous records.
`InformationVerificationFailed`	Information verification failed.	Unable to verify the provided information.

Business Specific

Code	Message	Description
`BusinessMissingUltimateBeneficialOwner`	Ultimate beneficial owner information is missing.	UBO details were not provided.
`BusinessIncompleteUltimateBeneficialOwner`	Ultimate beneficial owner information is incomplete.	UBO information lacks required fields.
`BusinessAwaitingUltimateBeneficialOwner`	Awaiting ultimate beneficial owner information.	UBO documentation is pending.
`BusinessRegistrationFailed`	Business registration verification failed.	Cannot verify business registration status.
`BusinessNotRegistered`	Business is not registered.	No registration found for the business entity.
`BusinessStructureUnclear`	Business structure is unclear.	Legal structure of business cannot be determined.
`BusinessLicenseExpired`	Business license has expired.	Required business license is no longer valid.
`BusinessLicenseInvalid`	Business license is invalid.	Business license verification failed.
`BusinessFormationDocumentMissing`	Business formation document is missing.	Articles of incorporation or equivalent not provided.
`BusinessOwnershipDocumentMissing`	Ownership document is missing.	Proof of ownership or shareholder documents not provided.
`BusinessDissolved`	Business appears to be dissolved.	Records indicate business has been closed or dissolved.
`BusinessHighRiskIndustry`	Business operates in a high-risk industry.	Industry sector is categorized as high-risk.

Behavioral & Fraud Detection

Code	Message	Description
`FraudMultipleAttempts`	Multiple suspicious attempts detected.	Unusual number of verification attempts detected.
`FraudVelocityCheck`	Velocity checks were triggered.	Activity frequency exceeds normal patterns.
`FraudSuspiciousBehaviour`	Suspicious behavior detected.	User actions indicate potentially fraudulent intent.
`FraudSuspiciousPattern`	Suspicious pattern detected.	Behavior matches known fraud patterns.
`FraudDeviceReputation`	Device has a poor reputation.	Device is associated with fraudulent activity.
`FraudIpReputation`	IP address has a poor reputation.	IP address is flagged for suspicious activity.
`FraudIpSuspicious`	Suspicious IP address detected.	IP characteristics indicate potential fraud.
`FraudTorDetected`	Tor usage detected.	Connection through Tor network identified.
`FraudVpnDetected`	VPN usage detected.	Connection through VPN or proxy identified.
`FraudBotDetected`	Bot activity detected.	Automated/non-human interaction detected.
`FraudSyntheticIdentity`	Synthetic identity is suspected.	Identity appears to be artificially constructed.
`FraudBrowserPreviouslyAttempted`	Browser was used in previous attempts.	Browser fingerprint matches previous submissions.
`FraudIpPreviouslyAttempted`	IP address was used in previous attempts.	IP address linked to other verification attempts.

Database & Lookup

Code	Message	Description
`DatabaseLookupFailed`	Database lookup failed.	Error occurred during database verification.
`DatabaseLookupSourceDown`	Data source is unavailable.	External verification database is unreachable.
`DatabaseLookupFaceNotFound`	Face not found in database.	Biometric not found in verification databases.
`DatabaseLookupIssue`	Issue encountered during database lookup.	Problem occurred accessing verification data.
`DatabaseNoCheckPerformed`	No database check was performed.	Database verification was not attempted.
`DatabaseCannotVerify`	Database cannot verify the information.	Information not found in authoritative databases.
`DatabaseCannotExtractMetadata`	Database cannot extract required metadata.	Unable to retrieve necessary data from verification sources.

Technical & System

Code	Message	Description
`TechnicalVerificationError`	Verification failed due to a technical error.	System error prevented completion of verification.
`TechnicalSystemError`	A system error occurred during verification.	Internal system failure during processing.
`TechnicalProcessingError`	A processing error occurred during verification.	Error in verification workflow execution.
`TechnicalTimeout`	Verification request timed out.	Verification took too long to complete.
`TechnicalApiError`	Upstream API error occurred during verification.	Third-party service error prevented verification.
`TechnicalCannotProcess`	The request cannot be processed.	Submission cannot be handled by the system.
`TechnicalPrivacyBlocked`	Verification was blocked due to privacy restrictions.	Privacy settings prevent verification completion.
`TechnicalDataRequirementsNotMet`	Data requirements for verification were not met.	Submission doesn’t meet minimum data requirements.

Other & General

Code	Message	Description
`OtherManualReviewFailed`	Manual review failed.	Human review determined submission should be rejected.
`OtherManualReviewRequired`	Manual review is required.	Submission requires human review before approval.
`OtherTermsNotAccepted`	Terms were not accepted.	User did not accept required terms and conditions.
`OtherUnspecified`	Unspecified compliance rejection.	Rejection reason doesn’t fit standard categories.
`OtherCustomError`	Custom compliance rejection reason.	Provider-specific rejection not mapped to standard codes.

Usage Notes

Multiple Reasons: A compliance check may have multiple rejection reasons when the PFI identifies several issues.
Code Consistency: The code field is standardized across all PFIs, allowing for consistent handling of rejection reasons in your application logic.
Provider Messages: The pfiMessage field contains the original message from the verification provider and may vary in format and detail across different PFIs.
Description Mapping: The description field is automatically derived from the code enum value and provides a consistent human-readable message.
Actionability: Some rejection codes indicate user-correctable issues (e.g., DocumentExpired, DocumentBlurry) while others indicate systemic blocks (e.g., ComplianceSanctionsMatch, GeographicProhibitedCountry).

Integration Recommendations

Display Strategy: Show the description to end users for clarity, and log the pfiMessage for debugging and support purposes.
Retry Logic: Implement different retry strategies based on rejection codes (e.g., allow retries for quality issues but not for compliance flags).
User Guidance: Map specific codes to actionable user instructions (e.g., “Please retake photo in better lighting” for DocumentBlurry).
Analytics: Track rejection code frequency to identify common user issues and improve the verification flow.

If you have any questions, please don’t hesitate to reach out to us via email or slack.

Getting Started

Core Concepts

Transaction Types

Products

Identities & Compliance

Identity types

Compliance details

Working with identities & compliance

Create a personal identity

Step 1: Initiate identity object

Step 2: Gather configured PFIs

Step 3: Check required documents

Step 4: Attach required documents

Step 5: Start compliance check

Create a business identity

Step 1: Initiate identity object

Step 2: Gather configured PFIs

Step 3: Check required documents

Step 4: Attach required documents

Step 5: Start compliance check

Handle compliance rejection

Response Structure

Example Response

Rejection Reason Codes Reference

Document Quality & Detection

Document Fraud & Tampering

Document Data & MRZ

Identity Verification

Biometric & Face

Address Verification

Geographic Restrictions

Compliance & AML

Information Completeness

Business Specific

Behavioral & Fraud Detection

Database & Lookup

Technical & System

Other & General

Usage Notes

Integration Recommendations

Getting Started

Core Concepts

Transaction Types

Products

​Identity types

​Compliance details

​Working with identities & compliance

​Create a personal identity

​Step 1: Initiate identity object

​Step 2: Gather configured PFIs

​Step 3: Check required documents

​Step 4: Attach required documents

​Step 5: Start compliance check

​Create a business identity

​Step 1: Initiate identity object

​Step 2: Gather configured PFIs

​Step 3: Check required documents

​Step 4: Attach required documents

​Step 5: Start compliance check

​Handle compliance rejection

​Response Structure

​Example Response

​Rejection Reason Codes Reference

​Document Quality & Detection

​Document Fraud & Tampering

​Document Data & MRZ

​Identity Verification

​Biometric & Face

​Address Verification

​Geographic Restrictions

​Compliance & AML

​Information Completeness

​Business Specific

​Behavioral & Fraud Detection

​Database & Lookup

​Technical & System

​Other & General

​Usage Notes

​Integration Recommendations

Identity types

Compliance details

Working with identities & compliance

Create a personal identity

Step 1: Initiate identity object

Step 2: Gather configured PFIs

Step 3: Check required documents

Step 4: Attach required documents

Step 5: Start compliance check

Create a business identity

Step 1: Initiate identity object

Step 2: Gather configured PFIs

Step 3: Check required documents

Step 4: Attach required documents

Step 5: Start compliance check

Handle compliance rejection

Response Structure

Example Response

Rejection Reason Codes Reference

Document Quality & Detection

Document Fraud & Tampering

Document Data & MRZ

Identity Verification

Biometric & Face

Address Verification

Geographic Restrictions

Compliance & AML

Information Completeness

Business Specific

Behavioral & Fraud Detection

Database & Lookup

Technical & System

Other & General

Usage Notes

Integration Recommendations