Verification

Create Verification

Create a verification process.

POST/v2/verifications

Create a verification process.

Request body

▸

▸typestringRequired

Verification type (FULL_CHECK | IDENTITY_CREDIT_CHECK).

▸languagestringOptionalDefaults to pl

Language used for communication with tenants (pl|en|ua), lowercase. Other values are rejected with 400.

▸numberOfTenantsnumberOptionalDefaults to 1

Number of tenant verifications with a joint affordability check to be performed within the created process. Must be between 1 and 5.

▸tenantsobject arrayOptional

If provided, an email with a verification link will be issued to each tenant.

▸emailstringRequired

Tenant's email.

▸propertyobjectRequired

Object containing details of the rented property. For IDENTITY_CREDIT_CHECK it can be made optional by an account setting - contact dev@simpl.rent.

▸rentnumberOptional

Rent amount with all fees included to compare with tenant's salary (required if type == FULL_CHECK).

▸citystringRequired

City where the property is located (1-200 characters).

▸streetstringOptional

Street where the property is located (1-200 characters). Omit the field if the property has no street name - an empty string is rejected.

▸postalCodestringRequired

Polish post code in format 00-000.

▸houseNumberstringRequired

House number of the property (1-10 characters).

▸flatNumberstringOptional

Flat number of the property (1-10 characters). Omit the field if there is no flat number - an empty string is rejected.

▸contactPersonobjectOptional

Person responsible for the tenant (for customer support purposes).

▸namestringRequired

Contact person's name.

▸emailstringRequired

Contact person's email.

▸phonestringRequired

Contact person's phone number.

▸referenceIdstringRequired

Unique ID of the verification process in the client system, up to 200 characters without spaces. It is used in the URL of other endpoints. If a verification with the same referenceId already exists, the request returns 409 Conflict.

▸projectIdstringOptional

Optionally specifies the target project for the verification (1-100 characters). Available only for project API keys. If the provided ID (unique per account) does not exist, the system creates a new project record with that identifier. It is not returned when fetching the verification.

▸callbackUrlstringOptional

Callback URL for process updates (see callback return object).

Returns

▸

▸verificationUrlstring

Verification link to share with the tenants. Returned with status 201 Created.

Request Example


curl --location --request POST 'https://api-test.simpl.rent/v2/verifications' \
     --header 'Authorization: <API key>' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "type": "FULL_CHECK",
        "language": "pl",
        "numberOfTenants": 1,
        "tenants": [
          {
            "email": "test@simpl.rent"
          }
        ],
        "property": {
          "rent": 1000,
          "city": "krakow",
          "street": "ul. Dluga",
          "houseNumber": "1",
          "flatNumber": "1",
          "postalCode": "00-000"
        },
        "contactPerson": {
          "name": "Marcin Nowak",
          "email": "marcin.nowak@example.com",
          "phone": "500 400 100"
        },
        "referenceId": "123",
        "projectId": "my-project-001",
        "callbackUrl": "https://simpl.rent"
      }'

Response Example - 201 Created


{
    "verificationUrl": "https://test.simpl.rent/start-weryfikacji/aBc12XyZ?cl=pl"
}

Responses:

201 - the verification was created.
400 - validation error, missing or incomplete property address, missing rent for FULL_CHECK, or no credits available for the requested type.
409 - a verification with the same referenceId already exists, or the account balance is insufficient.

Get Verification

GET/v2/verifications/{id}

Fetch verification process data.

Path parameters

▸

▸idstring

ID (referenceId) provided when creating the verification.

Returns

▸

▸referenceIdstring

ID (referenceId) provided when creating the verification.

▸tenantsobject array

Array of current verification states for each tenant in the process.

▸idstring

Tenant's ID. Empty string until the tenant starts the verification.

▸certificateIdstring

ID used to fetch the Tenant Certificate.

▸emailstring

Tenant's email. Empty string until the tenant starts the verification.

▸namestring

Tenant's name. Empty string until the tenant starts the verification.

▸surnamestring

Tenant's surname. Empty string until the tenant starts the verification.

▸identityCheckstring

Identity check status (NOT_STARTED|PENDING|PASSED|FAILED).

▸affordabilityCheckstring

Affordability check status (NOT_STARTED|PENDING|PASSED|FAILED). Always NOT_STARTED for IDENTITY_CREDIT_CHECK, which does not include the affordability check.

▸creditCheckstring

Credit check status (NOT_STARTED|SUBMITTED|PASSED|FAILED). SUBMITTED means the check is in progress.

▸sanctionsCheckstring or undefined

Sanctions check status (NOT_STARTED|SUBMITTED|PASSED|FAILED). Absent if sanctions checks are not enabled for the account - contact info@simpl.rent for more info.

▸finalStatusstring

Final status (NOT_STARTED|PENDING|PASSED|FAILED).

To obtain verification state explanations, use certificateId to download Tenant Certificate.

A canceled verification can no longer be fetched - the request returns 400. If no verification exists for the given id, the request returns 404.

Request Example


curl --location --request GET 'https://api-test.simpl.rent/v2/verifications/123' \
     --header 'Authorization: <API key>'

Cancel Verification

DELETE/v2/verifications/{id}

Cancel the verification process. The verification is cancelable only if the tenant has not performed any checks yet.

Path parameters

▸

▸idstring

ID (referenceId) provided when creating the verification.

Responses:

204 - the verification is canceled (also when it was already canceled).
400 - a tenant has already started the verification.
404 - no verification exists for the given id.

If the verification is not started, it will cancel itself after 14 days since the last update.

Request Example


curl --location --request DELETE 'https://api-test.simpl.rent/v2/verifications/123' \
     --header 'Authorization: <API key>'

Get Tenant Certificate

GET/v2/certificates/{id}

Fetch the Tenant Certificate PDF file.

Path parameters

▸

▸idstring

ID (certificateId) from tenant verification data.

Query parameters

▸

▸langstringOptionalDefaults to pl

Language of the certificate. Available options are 'en', 'pl', 'ua'. If not provided, the default language is 'pl'.

Returns

▸

▸pdfContent-Type: application/pdf

PDF file containing the tenant certificate.

Request Example


curl --location --request GET 'https://api-test.simpl.rent/v2/certificates/zved?lang=pl' \
     --header 'Authorization: <API key>' --output certificate.pdf

If the certificate cannot be fetched, the request returns 404 with an empty body.

Get Tenant Verification history

GET/v2/certificates/{id}/history

Fetch the Tenant Verification history link.

Path parameters

▸

▸idstring

ID (certificateId) from tenant verification data.

Query parameters

▸

▸langstringOptionalDefaults to pl

Language of the history. Available options are 'en', 'pl', 'ua'. If not provided, the default language is 'pl'.

Returns

▸

▸(response body)string

Plain-text URL of the Tenant Verification History page. The link expires after 15 minutes.

Request Example


curl --location --request GET 'https://api-test.simpl.rent/v2/certificates/k7l/history?lang=pl' \
     --header 'Authorization: <API key>'

If the history link cannot be generated, the request returns 404 with an empty body.

Send Verification Invitation/Reminder

POST/v2/verifications/{id}/invite

Send verification process invitation/reminder to a tenant.

Request body

▸

▸tenantobjectRequired

Tenant to invite.

▸emailstringRequired

Tenant's email.

Request Example


curl --location --request POST 'https://api-test.simpl.rent/v2/verifications/123/invite' \
--header 'Authorization: <API key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "tenant": {
    "email": "test@simpl.rent"
  }
}'

Responses:

200 - the invitation was sent (empty body).
404 - no verification exists for the given id.

Callback Return Object

Callback return object. It is sent on every change of a tenant verification and when the verification is canceled.

Fields

▸

▸referenceIdstring

Unique ID of the verification process in the client system.

▸verificationStatusstring or undefined

Verification status (CANCELED). Present only when the verification is canceled - then tenants are absent.

▸tenantsobject array or undefined

Array of tenants, the same as in Get Verification. Absent when the verification is canceled.

▸idstring

Tenant's ID.

▸certificateIdstring

Certificate ID.

▸emailstring

Tenant's email.

▸namestring

Tenant's name.

▸surnamestring

Tenant's surname.

▸identityCheckstring

Identity check status (see Get Verification).

▸affordabilityCheckstring

Affordability check status (see Get Verification).

▸creditCheckstring

Credit check status (see Get Verification).

▸sanctionsCheckstring or undefined

Sanctions check status (see Get Verification).

▸finalStatusstring

Final status (see Get Verification).

Callback Example - update


{
    "referenceId": "123",
    "tenants": [
        {
            "id": "k7l",
            "certificateId": "zved",
            "email": "test@simpl.rent",
            "name": "Jan",
            "surname": "Kowalski",
            "identityCheck": "PASSED",
            "affordabilityCheck": "PENDING",
            "creditCheck": "PASSED",
            "finalStatus": "PENDING"
        }
    ]
}

Callback Example - canceled


{
    "referenceId": "123",
    "verificationStatus": "CANCELED"
}