Introduction

Welcome to the Yorlet API Reference. The API is designed to use standard HTTP protocols and return JSON payloads in response to HTTP requests, and are internally implemented based on the RESTful principles.

Environments

Our API and Dashboard are available in two environments:

Name	API URL	Dashboard URL
Sandbox	https://api.yorlet.io	https://dashboard.yorlet.io
Production	https://api.yorlet.com	https://dashboard.yorlet.com

Authentication

Authenticated request

curl https://api.yorlet.com/v1/applications \
-H "Authorization: Bearer {API_KEY}" \

To use the API you must authenticate a request using your API key. You can find the key in the Dashboard. There are two API keys in the dashboard: Publishable and Secret. You can find out more about the differences here.

The API key should be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer {API_KEY}

Errors

The error object

{
  "error": {
    "message": "The supplied customer was not found.",
    "param": "customer",
    "type": "invalid_request"
  },
  "status": 404
}

Yorlet uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Yorlet's servers.

Attributes

error object
The error object.

error.message string
A human-readable message providing more details about the error.

error.param string
If the error is parameter-specific, the parameter related to the error.

error.type string
The type of error returned.
status integer
The status code.

Error code	Meaning
`400` Bad Request	The request was unacceptable, often due to missing a required parameter.
`401` Unauthorized	No valid API key was provided.
`403` Forbidden	The API key doesn't have permissions to perform the request.
`404` Not Found	The requested resource doesn't exist.
`429` Too Many Requests	Too many requests hit the API too quickly.
`5XX` Server Error	We had a problem with our server. Try again later.

Expanding Objects

Application with expanded unit

curl https://api.yorlet.com/v1/applications/app_ki8ufmnsFtvwQmmL \
-H "Authorization: Bearer {access_token}" \
-d "expand[]"=unit \
-G

Many objects contain the ID of a related object in their response properties. For example, an Application may have an associated Unit ID. Those objects can be expanded inline with the expand request parameter. Objects that can be expanded are noted in this documentation. This parameter is available on all API requests, and applies to the response of that request only.

You can expand multiple objects at once by identifying multiple items in the expand array.

Core Resources

Applications

Endpoints

POST    /v1/applications

Application objects allow you to create new leases, accept move-in payments and set up contracts. The API allows you to create, delete, and update your applications. You can retrieve individual applications as well as a list of all your applications.

The application object

The application object

{
  "id": "app_test",
  "object": "application",
  "created": 1627210800,
  "account_collection_data": null,
  "applicant_requests": null,
  "auto_apply_unit_fees": false,
  "break_clause": {
    "notification_date": null,
    "terms": null
  },
  "building": null,
  "building_snapshot": {},
  "cancel_reason": null,
  "cancel_reason_description": null,
  "contract": null,
  "checkin_time": null,
  "checkout_time": null,
  "completed_at": null,
  "contract_address": null,
  "contract_legal_entity": null,
  "contract_template": null,
  "create_contract_on_accept": false,
  "currency": "gbp",
  "customer_emails": [],
  "customers": [],
  "date_end": null,
  "date_start": null,
  "deposit": {},
  "description": null,
  "end_behavior": null,
  "enquiry": null,
  "has_owner": false,
  "holding_fee_required": false,
  "metadata": {},
  "move_in_date": null,
  "move_out_date": null,
  "open": false,
  "owner_signature_required": false,
  "post_application_payment_session": null,
  "renewal_intent": null,
  "rent_term": null,
  "send_owner_contract": false,
  "subscription_data": null,
  "status": null,
  "tenancy_created": false,
  "tenancy_timestamp": null,
  "type": "standard",
  "unit": null,
  "unit_snapshot": {
    "epc_file": null,
    "name": null
  }
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be application.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
account_collection_data object
The account collection data for the application.
advance_rent integer
The amount of advance rent to be paid.
applicant_requests string
The applicant requests on the application.
auto_apply_unit_fees string
Whether or not to apply unit fees to owner records after the application completes.
break_clause object
The break clause for the application.
building stringexpandable
The building the application is for.
building_snapshot object
The snapshot of the building at the time of application.
cancel_reason string
The reason for cancelling the application.
cancel_reason_description string
The description for cancelling the application.
contract stringexpandable
The contract for the application.
checkin_time string
The checkin time for the application.
checkout_time string
The checkout time for the application.
completed_at timestamp
Measured in seconds since the Unix epoch.
contract_address string
The address of the contract for the application.
contract_legal_entity string
The legal entity for the contract, if provided this replaces the owner.
contract_template stringexpandable
The contract template for the application.
create_contract_on_accept boolean
Whether or not to create a contract on acceptance.
currency string
The currency for the application.
customer_emails array
The customer emails for the application.
customers array
The customers for the application.
date_end timestamp
Measured in seconds since the Unix epoch.
date_start timestamp
Measured in seconds since the Unix epoch.
deposit object
The deposit for the application.
description string
An arbitrary string attached to the object. Often useful for displaying to users.
end_behavior string
The end behavior for the application. Can be complete or roll.
enquiry string
The enquiry for the application.
has_owner boolean
Whether or not the application has an owner.
holding_fee object
The amount of holding fee to be paid.
holding_fee_required boolean
Whether or not the application requires a holding fee.
metadata string
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
move_in_date timestamp
The date the tenant is expected to move in. Useful for short term lets where the actual move in date may differ from the contractual move in date. Measured in seconds since the Unix epoch.
move_out_date timestamp
The date the tenant is expected to move out. Useful for short term lets where the actual move out date may differ from the contractual move out date. Measured in seconds since the Unix epoch.
open boolean
Whether or not the application is open.
owner_signature_required boolean
Whether or not the owner signature is required.
post_application_payment_session object
The payment session data for the application. If set this creates a payment session after the contract is signed.
renewal_intent stringexpandable
The renewal intent for the application.
rent_term string
The rent term for the application.
send_owner_contract boolean
Whether or not to send the owner contract.
subscription_data object
The subscription data for the application.
status string
The status of the application.
tenancy_created boolean
Whether or not the tenancy has been created.
tenancy_timestamp timestamp
Measured in seconds since the Unix epoch.
type string
The type of the application.
unit stringexpandable
The unit for the application.
unit_snapshot object
The unit snapshot at the time of application.

unit_snapshot.epc_file string
The EPC file for the unit.

unit_snapshot.name string
The name of the unit.

Create an application

POST /v1/applications

curl https://api.yorlet.com/v1/applications \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{
  "email": "[email protected]"
}'

Example Response

{
  "id": "cus_test",
  "object": "customer",
  "created": 1627210800,
  "archived": false,
  "default_payment_method": null,
  "delinquent": false,
  "description": null,
  "email": "[email protected]",
  "invoice_prefix": null,
  "metadata": {},
  "invoicing": {
    "arrears_emails": true,
    "email_to": null,
    "email_cc": []
  },
  "next_invoice_sequence": 1,
  "legal_completed": false,
  "legal": {},
  "name": "Jane Doe",
  "resident": false
}

Creates a new application.

Parameters

applicants required array
The applicants.

applicants.share_of_rent required number
The applicant's share of the rent.

applicants.create_reference optional boolean
Whether to create a reference for the applicant.

applicants.customer optional
The customer ID of the applicant.

applicants.customer_data optional object
The customer data of the applicant. Must be supplied if customer ID is not provided.

applicants.customer_data.email required
The email address of the customer.

applicants.customer_data.legal optional object
The customer's legal information. Used for generating contracts.

applicants.customer_data.legal.first_name required
The customer's full legal firstname.

applicants.customer_data.legal.last_name required
The customer's full legal lastname.

applicants.customer_data.legal.dob optional object
The customer's date of birth

applicants.customer_data.legal.dob.day required integer
The customer's day of birth

applicants.customer_data.legal.dob.month required integer
The customer's month of birth

applicants.customer_data.legal.dob.year required integer
The customer's year of birth

applicants.customer_data.name optional
The customer's full name.

applicants.customer_data.phone optional
The customer's phone number.

applicants.lead_tenant optional boolean
Whether the applicant is the lead tenant.

applicants.permitted_occupier optional boolean
Whether the applicant is a permitted occupier.

applicants.reference_data optional object
The applicant's reference data.

applicants.reference_data.automatic_reference optional object

applicants.reference_data.automatic_reference.enabled required boolean
Whether to enable automatic references.

applicants.reference_data.automatic_reference.provider required
The reference provider. Can be canopy.
end_date required
The end date of the tenancy. When null the tenancy will roll periodically.
start_date required
The start date of the tenancy.
subscription_data required object
The subscription data for the subscription.

subscription_data.collection_method required
The collection method for the subscription. Can be charge_automatically or send_invoice.

subscription_data.interval required
The interval of the subscription. Can be month, week, custom or upfront.

subscription_data.interval_count required integer
The interval count of the subscription.

subscription_data.add_invoice_items optional array
A list of up to 10 invoice items that will be appended to the next invoice for this subscription.

subscription_data.add_invoice_items.type required
The type of subscription item. Can be rent, charge or product.

subscription_data.add_invoice_items.description optional
Description for the subscription item.

subscription_data.add_invoice_items.metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

subscription_data.add_invoice_items.price optional
The ID of the price object.

subscription_data.add_invoice_items.price_data optional object
The price data for the subscription item.

subscription_data.add_invoice_items.price_data.amount required integer
A positive integer in pence representing how much to charge.

subscription_data.add_invoice_items.price_data.currency required
Three-letter ISO currency code, in lowercase.

subscription_data.add_invoice_items.price_data.tax_percent optional number
The percentage of sales tax to charge. For example, VAT would be 20.

subscription_data.add_invoice_items.proration_behavior optional
Can be create_prorations or none.

subscription_data.add_invoice_items.tax_percent optional number
The percentage of sales tax to charge. For example, VAT would be 20.

subscription_data.add_invoice_items.transfer_behavior optional
Can be automatic, owner or none.

subscription_data.add_invoice_items.transfer_destination optional
ID of the owner that will be the transfer destination. Only allowed when the subscription item transfer behavior is owner.

subscription_data.add_invoice_items.unit optional
The ID of the unit. If type=rent you must provide a unit ID

subscription_data.billing_anchor optional
The date to anchor the subscription to.

subscription_data.coupon optional
The ID of the coupon to apply to the subscription.

subscription_data.days_before_collection optional integer
The number of days to create the invoice before the subscription's next billing date. Useful if you want to send the customer the upcoming invoice a few days before the subscription's next billing date. Only applies to subscriptions with collection_method=send_invoice.

subscription_data.days_until_due optional integer
The number of days before the invoice is due.

subscription_data.end_date optional
The date this subscription should end. When a subscription ends the status will change to complete

subscription_data.items optional array
A list of up to 10 subscription items, each with attached price_data.

subscription_data.items.type required
The type of subscription item. Can be rent, charge or product.

subscription_data.items.description optional
Description for the subscription item.

subscription_data.items.metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

subscription_data.items.price optional
The ID of the price object.

subscription_data.items.price_data optional object
The price data for the subscription item.

subscription_data.items.price_data.amount required integer
A positive integer in pence representing how much to charge.

subscription_data.items.price_data.currency required
Three-letter ISO currency code, in lowercase.

subscription_data.items.price_data.tax_percent optional number
The percentage of sales tax to charge. For example, VAT would be 20.

subscription_data.items.proration_behavior optional
Can be create_prorations or none.

subscription_data.items.tax_percent optional number
The percentage of sales tax to charge. For example, VAT would be 20.

subscription_data.items.transfer_behavior optional
Can be automatic, owner or none.

subscription_data.items.transfer_destination optional
ID of the owner that will be the transfer destination. Only allowed when the subscription item transfer behavior is owner.

subscription_data.items.unit optional
The ID of the unit. If type=rent you must provide a unit ID

subscription_data.phases optional array
The phases of the subscription. Only allowed when interval=custom.

subscription_data.phases.start_date required
The date on which the phase starts.

subscription_data.phases.items optional array
A list of up to 10 subscription items, each with attached price_data.

subscription_data.phases.items.type required
The type of subscription item. Can be rent, charge or product.

subscription_data.phases.items.description optional
Description for the subscription item.

subscription_data.phases.items.metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

subscription_data.phases.items.price optional
The ID of the price object.

subscription_data.phases.items.price_data optional object
The price data for the subscription item.

subscription_data.phases.items.price_data.amount required integer
A positive integer in pence representing how much to charge.

subscription_data.phases.items.price_data.currency required
Three-letter ISO currency code, in lowercase.

subscription_data.phases.items.price_data.tax_percent optional number
The percentage of sales tax to charge. For example, VAT would be 20.

subscription_data.phases.items.proration_behavior optional
Can be create_prorations or none.

subscription_data.phases.items.tax_percent optional number
The percentage of sales tax to charge. For example, VAT would be 20.

subscription_data.phases.items.transfer_behavior optional
Can be automatic, owner or none.

subscription_data.phases.items.transfer_destination optional
ID of the owner that will be the transfer destination. Only allowed when the subscription item transfer behavior is owner.

subscription_data.phases.items.unit optional
The ID of the unit. If type=rent you must provide a unit ID

subscription_data.start_date optional
The date this subscription should begin. Start dates in the future will cause the initial status of the sunscription to be scheduled
type required
The application type. Can be standard, active_tenancy, renewal or let_only.
unit required
The unit ID.
accept optional boolean
Set to true to attempt to accept this application immediately. The parameter defaults to false and is only allowed when type=active_tenancy.
account_collection_data optional object
The account collection data, this overwrites any existing unit fees.

account_collection_data.amount required integer
The amount to charge.
advance_rent optional integer
The amount of advance rent to charge.
applicant_requests optional
The applicant special requests.
auto_apply_unit_fees optional boolean
Whether to automatically apply the unit's fees.
automatic_deposit_registration optional object

automatic_deposit_registration.branch_id optional

automatic_deposit_registration.scheme optional

automatic_deposit_registration.scheme_type optional
break_clause optional object
The break clause data.

break_clause.notification_date optional
The break clause notification date.

break_clause.terms optional
The break clause terms.
checkin_time optional
The checkin time.
checkout_time optional
The checkout time.
completion_behavior optional
The completion behavior for the application. Can be automatic or manual.
contract optional
The contract's ID.
contract_address optional
The contract address. Passing this field will update the contract address on the selected unit record.
contract_legal_entity optional
The legal entity for the contract, if provided this replaces the owner legal details.
create_contract_on_accept optional boolean
Whether to create a contract when the application is accepted.
create_deposit optional boolean
Whether to create a deposit object when the deposit payments have been collected.
currency optional
Three-letter ISO currency code, in lowercase.
deposit optional integer
The deposit amount.
deposit_data optional object
The deposit data for the application.

deposit_data.automatic_deposit optional object
The automatic deposit hash.

deposit_data.automatic_deposit.branch_id optional
The ID of the branch to use for the deposit.

deposit_data.automatic_deposit.enabled optional boolean
Whether to enable automatic deposits.

deposit_data.handled_externally optional boolean
Whether the deposit is handled externally or not. Usually this means the landlord or a thrid party has registered the deposit and will handle it.

deposit_data.scheme optional object
The deposit scheme information.

deposit_data.scheme.provider required
The deposit provider. Can be dps, mydeposits or tds.

deposit_data.scheme.type required
The deposit type. Can be custodial or insured.
end_behavior optional
The end behavior for the application. If there is a end date set at the end of the tenancy, complete will ensure that the tenancy is marked as complete, roll will ensure that the tenancy starts to roll periodically. Only allowed if end_date is set.
enquiry optional
The enquiry's ID.
holding_fee optional integer
The holding fee amount.
insurance optional object

insurance.rent_protection optional object

insurance.rent_protection.automatic optional boolean
Whether to enable automatic rent protection.

insurance.rent_protection.provider optional
The rent protection provider. Can be alan_boswell.
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
move_in_date optional
The date the tenant is expected to move in. Useful for short term lets where the actual move in date may differ from the contractual move in date.
move_out_date optional
The date the tenant is expected to move out. Useful for short term lets where the actual move out date may differ from the contractual move out date.
owner_signature_required optional boolean
Whether the owner signature is required.
post_application_payment_session optional object
The payment session data for the application.

post_application_payment_session.amount required integer
The amount to charge.

post_application_payment_session.description required
The description of the payment session.

post_application_payment_session.payment_method_types required array

post_application_payment_session.reporting_type optional
The reporting type of the transaction. Defaults to charge. Can be advance_rent, charge, deposit, holding_fee or rent.
renewal_days_before_end optional integer
The number of days before the end of the tenancy to renew it.
renewal_intent optional
The renewal intent to create this application with.
send_email optional boolean
Whether to send emails to the applicants.
send_owner_contract optional boolean
Whether to send the owner the contract on completion.

Returns

Returns the customer object if the request succeeded.

Buildings

Endpoints

POST    /v1/buildings
GET     /v1/buildings/:id
POST    /v1/buildings/:id
DELETE  /v1/buildings/:id
GET     /v1/buildings

Building objects are a core resource and allow you to create units. The API allows you to create, delete, and update your buildings. You can retrieve individual buildings as well as a list of all your buildings.

The building object

The building object

{
  "id": "build_test",
  "object": "building",
  "created": 1627210800,
  "accounting_code": null,
  "currency": "gbp",
  "description": null,
  "metadata": {},
  "name": null,
  "single_unit": false,
  "type": null,
  "unit_fees": {
    "management_fee": null,
    "management_fee_amount": null,
    "management_fee_type": "percentage",
    "renewal_fee": null,
    "tax": null,
    "tax_behavior": "exclusive",
    "tenant_find_fee": null
  }
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be building.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
accounting_code string
The accounting code to be used with invoice items associated with this building.
active boolean
Whether the building is currently available for use.
address integer
The building's address.
currency string
Three-letter ISO currency code, in lowercase. Must be a supported currency.
description string
An arbitrary string attached to the object. Often useful for displaying to users.
metadata object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
name string
The building's name.
single_unit boolean
Whether the building can only have a single unit.
type string
The building's type. Can be block_management, commercial, residential or student.
unit_fees object

unit_fees.management_fee float
The default management fee to apply to units. Maximum decimal precision of 2.

unit_fees.management_fee_amount integer
The default management fee fixed amount, represented as a whole integer in the smallest currency unit.

unit_fees.management_fee_type string
The management fee type. Can be percentage or fixed.

unit_fees.renewal_fee integer
The default renewal fee to apply to units, represented as a whole integer in the smallest currency unit.

unit_fees.tax float
The default tax to apply to units. Maximum decimal precision of 2.

unit_fees.tax_behavior string
The default tax behavior to apply to units. One of exclusive or inclusive. Can be exclusive or inclusive.

unit_fees.tenant_find_fee integer
The default tenant find fee to apply to units, represented as a whole integer in the smallest currency unit.

Create a building

POST /v1/buildings

curl https://api.yorlet.com/v1/buildings \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "build_test",
  "object": "building",
  "created": 1627210800,
  "accounting_code": null,
  "currency": "gbp",
  "description": null,
  "metadata": {},
  "name": null,
  "single_unit": false,
  "type": null,
  "unit_fees": {
    "management_fee": null,
    "management_fee_amount": null,
    "management_fee_type": "percentage",
    "renewal_fee": null,
    "tax": null,
    "tax_behavior": "exclusive",
    "tenant_find_fee": null
  }
}

Creates a new building.

Parameters

address required object
The building's address.

address.country required
Two-letter country code (ISO 3166-1 alpha-2).

address.line1 required
Address line 1 (e.g., street, PO Box, or company name).

address.city optional
City, district, suburb, town, or village.

address.line2 optional
Address line 2 (e.g., apartment, suite, unit, or building).

address.postal_code optional
Postal code.

address.state optional
State, county, province, or region.
name required
The building's name.
accounting_code optional
active optional boolean
currency optional
The default currency for the building and any units associated with the building. Can be eur, gbp, sek or usd.
description optional
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
single_unit optional boolean
type optional
Can be block_management, commercial, residential or student.
unit_fees optional object

unit_fees.management_fee optional number
The unit's management fee percentage amount.

unit_fees.management_fee_amount optional integer
The unit's management fee fixed amount.

unit_fees.management_fee_type optional
Can be percentage or fixed.

unit_fees.renewal_fee optional integer
The unit's renewal fee.

unit_fees.tax optional number
The tax to apply to the unit fees.

unit_fees.tax_behavior optional
Whether the tax is included or excluded from the fees. Can be inclusive or exclusive.

unit_fees.tenant_find_fee optional integer
The unit's tenant find fee.

Returns

Returns the building object if the request succeeded.

Retrieve a building

GET /v1/buildings/:id

curl https://api.yorlet.com/v1/buildings/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "build_test",
  "object": "building",
  "created": 1627210800,
  "accounting_code": null,
  "currency": "gbp",
  "description": null,
  "metadata": {},
  "name": null,
  "single_unit": false,
  "type": null,
  "unit_fees": {
    "management_fee": null,
    "management_fee_amount": null,
    "management_fee_type": "percentage",
    "renewal_fee": null,
    "tax": null,
    "tax_behavior": "exclusive",
    "tenant_find_fee": null
  }
}

Retrieves the building with the given ID.

Parameters

No parameters

Returns

Returns a building object if a valid identifier was provided.

Update a building

POST /v1/buildings/:id

curl https://api.yorlet.com/v1/buildings/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "build_test",
  "object": "building",
  "created": 1627210800,
  "accounting_code": null,
  "currency": "gbp",
  "description": null,
  "metadata": {},
  "name": null,
  "single_unit": false,
  "type": null,
  "unit_fees": {
    "management_fee": null,
    "management_fee_amount": null,
    "management_fee_type": "percentage",
    "renewal_fee": null,
    "tax": null,
    "tax_behavior": "exclusive",
    "tenant_find_fee": null
  }
}

Updates the specified building by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

accounting_code optional
active optional boolean
address optional object
The building's address.

address.country required
Two-letter country code (ISO 3166-1 alpha-2).

address.line1 required
Address line 1 (e.g., street, PO Box, or company name).

address.city optional
City, district, suburb, town, or village.

address.line2 optional
Address line 2 (e.g., apartment, suite, unit, or building).

address.postal_code optional
Postal code.

address.state optional
State, county, province, or region.
description optional
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
name optional
The building's name.
type optional
Can be block_management, commercial, residential or student.
unit_fees optional object

unit_fees.management_fee optional number
The unit's management fee percentage amount.

unit_fees.management_fee_amount optional integer
The unit's management fee fixed amount.

unit_fees.management_fee_type optional
Can be percentage or fixed.

unit_fees.renewal_fee optional integer
The unit's renewal fee.

unit_fees.tax optional number
The tax to apply to the unit fees.

unit_fees.tax_behavior optional
Whether the tax is included or excluded from the fees. Can be inclusive or exclusive.

unit_fees.tenant_find_fee optional integer
The unit's tenant find fee.

Returns

Returns the building object if the update succeeded.

Delete a building

DELETE /v1/buildings/:id

curl https://api.yorlet.com/v1/buildings/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "build_test",
  "object": "building",
  "deleted": true
}

Permanently deletes a buidling. This cannot be undone.

Parameters

No parameters

Returns

Returns an object with a deleted parameter on success. If the building ID does not exist, this call throws an error.

List all buildings

GET /v1/buildings

curl https://api.yorlet.com/v1/buildings \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "build_test",
      "object": "building",
      "created": 1627210800,
      "accounting_code": null,
      "currency": "gbp",
      "description": null,
      "metadata": {},
      "name": null,
      "single_unit": false,
      "type": null,
      "unit_fees": {
        "management_fee": null,
        "management_fee_amount": null,
        "management_fee_type": "percentage",
        "renewal_fee": null,
        "tax": null,
        "tax_behavior": "exclusive",
        "tenant_find_fee": null
      }
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of buildings. The buildings are returned sorted by creation date, with the most recent buildings appearing first.

Parameters

No parameters

Returns

A object with a data property that contains an array of buildings.

Customers

Endpoints

POST    /v1/customers
GET     /v1/customers/:id
POST    /v1/customers/:id
DELETE  /v1/customers/:id
GET     /v1/customers

Customer objects allow you to create applications, accept payments and manage subscriptions. The API allows you to create, delete, and update your customers. You can retrieve individual customers as well as a list of all your customers.

The customer object

The customer object

{
  "id": "cus_test",
  "object": "customer",
  "created": 1627210800,
  "archived": false,
  "default_payment_method": null,
  "delinquent": false,
  "description": null,
  "email": "[email protected]",
  "invoice_prefix": null,
  "metadata": {},
  "invoicing": {
    "arrears_emails": true,
    "email_to": null,
    "email_cc": []
  },
  "next_invoice_sequence": 1,
  "legal_completed": false,
  "legal": {},
  "name": "Jane Doe",
  "resident": false
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be customer.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
address object
The customer’s address.
archived boolean
Whether the customer is archived. An archived customer cannot have applications, invoices, subscriptions, or payments create against them.
default_payment_method stringexpandable
ID of the default payment method for the customer.
delinquent boolean
A boolean to indicate whether the customer has any outstanding invoices.
description string
An arbitrary string attached to the object. Often useful for displaying to users.
email string
The customer’s email address.
invoice_prefix string
The prefix for the customer used to generate unique invoice numbers.
metadata string
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
invoicing object
The customer’s invoicing settings.

invoicing.email_to string
The email address to send invoices to.

invoicing.email_cc array
List of emails to CC in the invoice email.
next_invoice_sequence string
The suffix of the customer’s next invoice number, e.g., 0001.
legal_completed boolean
Whether the customer's legal information is completed.
legal object
The customer's legal information.
name string
The customer's name.
phone string
The customer's phone number.
resident boolean
Whether the customer is currently an active resident.

Create a customer

POST /v1/customers

curl https://api.yorlet.com/v1/customers \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{
  "email": "[email protected]"
}'

Example Response

{
  "id": "cus_test",
  "object": "customer",
  "created": 1627210800,
  "archived": false,
  "default_payment_method": null,
  "delinquent": false,
  "description": null,
  "email": "[email protected]",
  "invoice_prefix": null,
  "metadata": {},
  "invoicing": {
    "arrears_emails": true,
    "email_to": null,
    "email_cc": []
  },
  "next_invoice_sequence": 1,
  "legal_completed": false,
  "legal": {},
  "name": "Jane Doe",
  "resident": false
}

Creates a new customer.

Parameters

email required
The customer's email address.
address optional object
The customer's address.

address.country required
Two-letter country code (ISO 3166-1 alpha-2).

address.line1 required
Address line 1 (e.g., street, PO Box, or company name).

address.city optional
City, district, suburb, town, or village.

address.line2 optional
Address line 2 (e.g., apartment, suite, unit, or building).

address.postal_code optional
Postal code.

address.state optional
State, county, province, or region.
description optional
An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.
invoice_prefix optional
The prefix for the customer used to generate unique invoice numbers. Must be 3–12 uppercase letters or numbers.
invoicing optional object
The customer’s invoicing settings.

invoicing.arrears_emails optional boolean
Whether to send arrears emails to the customer.

invoicing.email_cc optional array
List of emails to CC in the invoice email.

invoicing.email_to optional
The email address to send invoices to.
legal optional object
The customer's legal information. Used for generating contracts.

legal.dob optional object

legal.dob.day required integer

legal.dob.month required integer

legal.dob.year required integer

legal.first_name optional
The customer's full legal firstname.

legal.last_name optional
The customer's full legal lastname.

legal.previous_addresses optional array
The customer's previous addresses.

legal.previous_addresses.country required
Two-letter country code (ISO 3166-1 alpha-2).

legal.previous_addresses.line1 required
Address line 1 (e.g., street, PO Box, or company name).

legal.previous_addresses.city optional
City, district, suburb, town, or village.

legal.previous_addresses.line2 optional
Address line 2 (e.g., apartment, suite, unit, or building).

legal.previous_addresses.postal_code optional
Postal code.

legal.previous_addresses.state optional
State, county, province, or region.
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
name optional
The customer's name.
next_invoice_sequence optional integer
The sequence to be used on the customer’s next invoice. Defaults to 1.
phone optional
The customer's phone number.

Returns

Returns the customer object if the request succeeded.

Retrieve a customer

GET /v1/customers/:id

curl https://api.yorlet.com/v1/customers/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "cus_test",
  "object": "customer",
  "created": 1627210800,
  "archived": false,
  "default_payment_method": null,
  "delinquent": false,
  "description": null,
  "email": "[email protected]",
  "invoice_prefix": null,
  "metadata": {},
  "invoicing": {
    "arrears_emails": true,
    "email_to": null,
    "email_cc": []
  },
  "next_invoice_sequence": 1,
  "legal_completed": false,
  "legal": {},
  "name": "Jane Doe",
  "resident": false
}

Retrieves the customer with the given ID.

Parameters

No parameters

Returns

Returns a customer object if a valid identifier was provided.

Update a customer

POST /v1/customers/:id

curl https://api.yorlet.com/v1/customers/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "cus_test",
  "object": "customer",
  "created": 1627210800,
  "archived": false,
  "default_payment_method": null,
  "delinquent": false,
  "description": null,
  "email": "[email protected]",
  "invoice_prefix": null,
  "metadata": {},
  "invoicing": {
    "arrears_emails": true,
    "email_to": null,
    "email_cc": []
  },
  "next_invoice_sequence": 1,
  "legal_completed": false,
  "legal": {},
  "name": "Jane Doe",
  "resident": false
}

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

address optional object
The customer's address.

address.country required
Two-letter country code (ISO 3166-1 alpha-2).

address.line1 required
Address line 1 (e.g., street, PO Box, or company name).

address.city optional
City, district, suburb, town, or village.

address.line2 optional
Address line 2 (e.g., apartment, suite, unit, or building).

address.postal_code optional
Postal code.

address.state optional
State, county, province, or region.
archived optional boolean
description optional
An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.
email optional
The customer's email address.
invoice_prefix optional
The prefix for the customer used to generate unique invoice numbers. Must be 3–12 uppercase letters or numbers.
invoicing optional object
The customer’s invoicing settings.

invoicing.arrears_emails optional boolean
Whether to send arrears emails to the customer.

invoicing.email_cc optional array
List of emails to CC in the invoice email.

invoicing.email_to optional
The email address to send invoices to.
legal optional object
The customer's legal information. Used for generating contracts.

legal.dob optional object

legal.dob.day required integer

legal.dob.month required integer

legal.dob.year required integer

legal.first_name optional
The customer's full legal firstname.

legal.last_name optional
The customer's full legal lastname.

legal.previous_addresses optional array
The customer's previous addresses.

legal.previous_addresses.country required
Two-letter country code (ISO 3166-1 alpha-2).

legal.previous_addresses.line1 required
Address line 1 (e.g., street, PO Box, or company name).

legal.previous_addresses.city optional
City, district, suburb, town, or village.

legal.previous_addresses.line2 optional
Address line 2 (e.g., apartment, suite, unit, or building).

legal.previous_addresses.postal_code optional
Postal code.

legal.previous_addresses.state optional
State, county, province, or region.
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
name optional
The customer's name.
next_invoice_sequence optional integer
The sequence to be used on the customer’s next invoice. Defaults to 1.
phone optional
The customer's phone number.

Returns

Returns the customer object if the update succeeded.

Delete a customer

DELETE /v1/customers/:id

curl https://api.yorlet.com/v1/customers/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "cus_test",
  "object": "customer",
  "deleted": true
}

Permanently deletes a customer. This cannot be undone.

Parameters

No parameters

Returns

Returns an object with a deleted parameter on success. If the customer ID does not exist, this call throws an error.

List all customers

GET /v1/customers

curl https://api.yorlet.com/v1/customers \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "cus_test",
      "object": "customer",
      "created": 1627210800,
      "archived": false,
      "default_payment_method": null,
      "delinquent": false,
      "description": null,
      "email": "[email protected]",
      "invoice_prefix": null,
      "metadata": {},
      "invoicing": {
        "arrears_emails": true,
        "email_to": null,
        "email_cc": []
      },
      "next_invoice_sequence": 1,
      "legal_completed": false,
      "legal": {},
      "name": "Jane Doe",
      "resident": false
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of customers. The customers are returned sorted by creation date, with the most recent customers appearing first.

Parameters

No parameters

Returns

A object with a data property that contains an array of customers.

Enquiries

Endpoints

POST    /v1/enquiries/

The enquiry object

The enquiry object

{
  "id": "enq_test",
  "object": "enquiry",
  "created": 1627210800,
  "assignee": null,
  "building": null,
  "customer": null,
  "declined_reason": 0,
  "declined_reason_description": null,
  "description": null,
  "email": null,
  "follow_up": null,
  "metadata": {},
  "name": null,
  "phone": null,
  "referral": {},
  "requirements": {
    "bedrooms": null,
    "budget_min": null,
    "budget_max": null,
    "move_in": null,
    "length_of_stay": null,
    "right_to_rent": null,
    "type": null
  },
  "selected_unit": null,
  "source": null,
  "status_transitions": {
    "application_completed_at": null,
    "application_created_at": null,
    "declined_at": null,
    "first_response_at": null,
    "viewing_created_at": null
  },
  "type": "lead"
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be enquiry.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
building stringexpandable
customer string
declined_reason string
declined_reason_description string
description string
email string
follow_up timestamp
metadata object
name string
phone string
referral object
requirements object
selected_unit string
source string
status string
status_transitions object
Measured in seconds since the Unix epoch.
type object

Create an enquiry

POST /v1/enquiries/

curl https://api.yorlet.com/v1/enquiries/ \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "enq_test",
  "object": "enquiry",
  "created": 1627210800,
  "assignee": null,
  "building": null,
  "customer": null,
  "declined_reason": 0,
  "declined_reason_description": null,
  "description": null,
  "email": null,
  "follow_up": null,
  "metadata": {},
  "name": null,
  "phone": null,
  "referral": {},
  "requirements": {
    "bedrooms": null,
    "budget_min": null,
    "budget_max": null,
    "move_in": null,
    "length_of_stay": null,
    "right_to_rent": null,
    "type": null
  },
  "selected_unit": null,
  "source": null,
  "status_transitions": {
    "application_completed_at": null,
    "application_created_at": null,
    "declined_at": null,
    "first_response_at": null,
    "viewing_created_at": null
  },
  "type": "lead"
}

Creates a new enquiry.

Parameters

building optional
customer optional
description optional
email optional
follow_up optional
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
name optional
phone optional
referral optional object

referral.campaign optional

referral.heard_from optional

referral.medium optional

referral.source optional
requirements optional object

requirements.balcony optional boolean

requirements.bedrooms optional integer

requirements.budget_max optional integer

requirements.budget_min optional integer

requirements.furnished optional boolean

requirements.length_of_stay optional

requirements.move_in optional
Can be asap, january, february, march, april, may, june, july, august, september, october, november or december.

requirements.parking optional boolean

requirements.pet_friendly optional boolean

requirements.right_to_rent optional
Can be not_provided, provided or certified.

requirements.type optional
Can be commercial, residential or student.
selected_unit optional
type optional

Returns

Returns a enquiry object.

Events

Endpoints

GET     /v1/events/:id
GET     /v1/events

Events let you know when something happens in your account.

The event object

The event object

{
  "id": "evt_test",
  "object": "event",
  "created": 1627210800,
  "account": null,
  "data": {},
  "request": {},
  "type": null
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be event.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
account string
data object
request object
type string

Retrieve an event

GET /v1/events/:id

curl https://api.yorlet.com/v1/events/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "evt_test",
  "object": "event",
  "created": 1627210800,
  "account": null,
  "data": {},
  "request": {},
  "type": null
}

Retrieves the details of the event that has previously been created. Supply the unique event ID.

Parameters

No parameters

Returns

Returns an event if a valid identifier was provided, and returns an error otherwise.

List all events

GET /v1/events

curl https://api.yorlet.com/v1/events \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "evt_test",
      "object": "event",
      "created": 1627210800,
      "account": null,
      "data": {},
      "request": {},
      "type": null
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of events previously created. The events are returned in sorted order, with the most recent events appearing first.

Parameters

No parameters

Returns

Returns a list of events if a valid identifier was provided, and returns an error otherwise.

Types of events

This is a list of all the types of events we currently send. We may add more at any time, so your code should handle unexpected event types.

Event

account.updated data.object of account
Occurs whenever an account is updated.
application.accepted data.object of application
Occurs whenever an application is accepted.

application.canceled data.object of application
Occurs whenever an application is canceled.

application.created data.object of application
Occurs whenever an application is created.

application.completed data.object of application
Occurs whenever an application is completed.

application.updated data.object of application
Occurs whenever an application is updated.
building.created data.object of building
Occurs whenever a building is created.

building.deleted data.object of building
Occurs whenever a building is deleted.

building.updated data.object of building
Occurs whenever a building is updated.
contract.created data.object of contract
Occurs whenever a contract is created.

contract.completed data.object of contract
Occurs whenever a contract is completed.

contract.out_for_signature data.object of contract
Occurs whenever a contract is sent out for signature.
customer.created data.object of customer
Occurs whenever a customer is created.

customer.deleted data.object of customer
Occurs whenever a customer is deleted.

customer.updated data.object of customer
Occurs whenever a customer is updated.
dispute.created data.object of dispute
Occurs whenever a dispute is created.

dispute.resolved data.object of dispute
Occurs whenever a dispute is resolved.
invoice.created data.object of invoice
Occurs whenever a invoice is created.

invoice.finalization_failed data.object of invoice
Occurs whenever a invoice fails finalization.

invoice.finalized data.object of invoice
Occurs whenever a invoice is finalized and marked as open.

invoice.paid data.object of invoice
Occurs whenever a invoice is paid.

invoice.payment_failed data.object of invoice
Occurs whenever a invoice payment fails.

invoice.sent data.object of invoice
Occurs whenever an invoice email is sent.

invoice.voided data.object of invoice
Occurs whenever a invoice is voided.
owner.created data.object of owners
Occurs whenever an owner is created.

owner.updated data.object of owners
Occurs whenever an owner us updated.
payment_method.chargeable data.object of payment method
Occurs whenever a payment method becomes chargeable.

payment_method.created data.object of payment method
Occurs whenever a payment method is created.

payment_method.failed data.object of payment method
Occurs whenever a payment method fails.
payment_method_transaction.created data.object of payment method transaction
Occurs whenever a payment method transaction is created.
payment_session.created data.object of payment session
Occurs whenever a payment session is created.

payment_session.paid data.object of payment session
Occurs whenever a payment session is paid.
renewal_intent.canceled data.object of renewal intent
Occurs whenever an renewal intent is canceled.

renewal_intent.created data.object of renewal intent
Occurs whenever an renewal intent is created.

renewal_intent.completed data.object of renewal intent
Occurs whenever an renewal intent is completed.

renewal_intent.updated data.object of renewal intent
Occurs whenever an renewal intent is updated.
subscription.canceled data.object of subscription
Occurs whenever a subscription is canceled.

subscription.completed data.object of subscription
Occurs whenever a subscription is completed.

subscription.created data.object of subscription
Occurs whenever a subscription is created.

subscription.updated data.object of subscription
Occurs whenever a subscription is updated.
tenancy.activated data.object of tenancy
Occurs whenever an tenancy is activated.

tenancy.canceled data.object of tenancy
Occurs whenever an tenancy is canceled.

tenancy.created data.object of tenancy
Occurs whenever an tenancy is created.

tenancy.completed data.object of tenancy
Occurs whenever an tenancy is completed.

tenancy.updated data.object of tenancy
Occurs whenever an tenancy is updated.
transaction.canceled data.object of transaction
Occurs whenever a transaction is canceled.

transaction.created data.object of transaction
Occurs whenever a transaction is created.

transaction.payment_failed data.object of transaction
Occurs whenever a transaction fails.

transaction.processing data.object of transaction
Occurs whenever a transaction is processing.

transaction.succeeded data.object of transaction
Occurs whenever a transaction has succeeded.
unit.archived data.object of unit
Occurs whenever a unit is archived.

unit.created data.object of unit
Occurs whenever a unit is created.

unit.deleted data.object of unit
Occurs whenever a unit is deleted.

unit.updated data.object of unit
Occurs whenever a unit is updated.
viewing.created data.object of viewing
Occurs whenever a viewing is created.

References

Endpoints

POST    /v1/references
GET     /v1/references/:id
POST    /v1/references/:id
GET     /v1/references

The reference object

The reference object

{
  "id": "ref_test",
  "object": "reference",
  "created": 1627210800,
  "application": null,
  "automatic_reference": {
    "enabled": false,
    "last_error": null,
    "outcome": null,
    "provider": null,
    "status": null
  },
  "completed_at": null,
  "customer": null,
  "description": null,
  "metadata": {},
  "outcome": null,
  "reference_pdf": null,
  "status": "pending",
  "type": "customer"
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be reference.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
application stringexpandable
The identifier of the application for the reference.
automatic_reference object
Automatic reference settings for this reference.

automatic_reference.canopy object
The automtic reference settings for Canopy.

automatic_reference.canopy.type string
The reference type. Can be instant or full.

automatic_reference.enabled boolean
Controls whether Yorlet will automatically reference the customer with the supplied provider.

automatic_reference.last_error object
The error encountered during the previous attempt to process the reference. This field is cleared when the reference is successfully completed.

automatic_reference.last_error.message string
A human-readable message providing more details about the error.

automatic_reference.last_error.type string
The type of error returned.

automatic_reference.outcome string
The provider outcome for the automatic reference.

automatic_reference.provider string
The provider to use with automatic referencing. Can be canopy.

automatic_reference.status string
The provider status for the automatic reference.
completed_at timestamp
Time at which the object was completed. Measured in seconds since the Unix epoch.
customer stringexpandable
The identifier of the customer to reference.
description string
An arbitrary string attached to the object. Often useful for displaying to users.
metadata object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
outcome string
The outcome of the reference. Can be accept, consider or high_risk.
reference_pdf string
(ID of a file upload) The completed reference PDF.
status string
The status of this reference. Can be pending, processing or complete.
type string
The type of the reference. Can be customer.

Create a reference

POST /v1/references

curl https://api.yorlet.com/v1/references \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{
  "customer": "{CUSTOMER_ID}",
  "type": "customer"
}'

Example Response

{
  "id": "ref_test",
  "object": "reference",
  "created": 1627210800,
  "application": null,
  "automatic_reference": {
    "enabled": false,
    "last_error": null,
    "outcome": null,
    "provider": null,
    "status": null
  },
  "completed_at": null,
  "customer": null,
  "description": null,
  "metadata": {},
  "outcome": null,
  "reference_pdf": null,
  "status": "pending",
  "type": "customer"
}

Creates a new reference.

Parameters

customer required
The identifier of the customer to reference.
type required
The reference type. Can be customer.
application optional
The identifier of the application for the reference.
automatic_reference optional object
Automatic reference settings for this reference.

automatic_reference.enabled required boolean
Enabled automatic reference will automatically reference the customer with a provider.

automatic_reference.provider required
The provider to use with automatic referencing. Can be canopy, homelet or let_alliance.

automatic_reference.canopy optional object
The automtic reference settings for Canopy.

automatic_reference.canopy.is_guarantor_needed optional boolean
Whether a guarantor is needed for the reference.

automatic_reference.canopy.item_type optional
The reference type. Can be full, instant, pre_qualification or priority.

automatic_reference.canopy.request_type optional
The request type. Can be renter_screening or guarantor_screening.
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Returns

Returns the Reference object if the request succeeded.

Retrieve a reference

GET /v1/references/:id

curl https://api.yorlet.com/v1/references/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "ref_test",
  "object": "reference",
  "created": 1627210800,
  "application": null,
  "automatic_reference": {
    "enabled": false,
    "last_error": null,
    "outcome": null,
    "provider": null,
    "status": null
  },
  "completed_at": null,
  "customer": null,
  "description": null,
  "metadata": {},
  "outcome": null,
  "reference_pdf": null,
  "status": "pending",
  "type": "customer"
}

Retrieves the reference with the given ID.

Parameters

No parameters

Returns

A Reference object if a valid identifier was provided.

Update a reference

POST /v1/references/:id

curl https://api.yorlet.com/v1/references/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "ref_test",
  "object": "reference",
  "created": 1627210800,
  "application": null,
  "automatic_reference": {
    "enabled": false,
    "last_error": null,
    "outcome": null,
    "provider": null,
    "status": null
  },
  "completed_at": null,
  "customer": null,
  "description": null,
  "metadata": {},
  "outcome": null,
  "reference_pdf": null,
  "status": "pending",
  "type": "customer"
}

Updates the reference with the given ID.

Parameters

metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
outcome optional
The outcome of the reference. Can be accept, consider or high_risk.
reference_pdf optional
The file of the completed reference PDF.

Returns

The updated reference. Otherwise, this call throws an error.

List all references

GET /v1/references

curl https://api.yorlet.com/v1/references \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "ref_test",
      "object": "reference",
      "created": 1627210800,
      "application": null,
      "automatic_reference": {
        "enabled": false,
        "last_error": null,
        "outcome": null,
        "provider": null,
        "status": null
      },
      "completed_at": null,
      "customer": null,
      "description": null,
      "metadata": {},
      "outcome": null,
      "reference_pdf": null,
      "status": "pending",
      "type": "customer"
    }
  ],
  "count": 1,
  "has_more": false
}

A list of references. The references are returned sorted by creation date, with the most recent references appearing first.

Parameters

No parameters

Returns

A object with a data property that contains an array of references.

Renewal Intents

Endpoints

POST    /v1/renewal_intents
GET     /v1/renewal_intents/:id
POST    /v1/renewal_intents/:id
POST    /v1/renewal_intents/:id/cancel
POST    /v1/renewal_intents/:id/complete
GET     /v1/renewal_intents

A Renewal Intent describes the stage of a potential renewal all the way to completing a renewal application or the customer leaving the tenancy.

The renewal intent object

The renewal intent object

{
  "id": "ri_test",
  "object": "renewal_intent",
  "created": 1627210800,
  "application": null,
  "canceled_at": null,
  "completed_at": null,
  "source_application": "app_test",
  "status": "pending",
  "type": null,
  "unit": null
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be renewal_intent.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
application stringexpandable
The ID of the renewal application this renewal intent created.
canceled_at timestamp
Time at which the renewal intent was canceled. Measured in seconds since the Unix epoch.
completed_at timestamp
Time at which the renewal intent was completed. Measured in seconds since the Unix epoch.
no_renewal object
A hash of the no_renewal data.

no_renewal.reason string
The reason code why the renewal intent was not renewed. Can be affordability, circumstance_change, relocating, unit_issue or other.

no_renewal.reason_description string
A description of why the renewal intent was not renewed.
renewal object
A hash of the renewal data.

renewal.end_date integer
The end date of the renewal.

renewal.start_date integer
The start date of the renewal.
source_application stringexpandable
The ID of the application this renewal intent is was created from.
status string
The status of the renewal intent. Can be pending, renewing, leaving or complete.
type string
The type of renewal intent. Will be null until the type is set. Can be null, renewal or no_renewal.
unit stringexpandable
The ID of the unit the source application was for.

Create a renewal intent

POST /v1/renewal_intents

curl https://api.yorlet.com/v1/renewal_intents \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "ri_test",
  "object": "renewal_intent",
  "created": 1627210800,
  "application": null,
  "canceled_at": null,
  "completed_at": null,
  "source_application": "app_test",
  "status": "pending",
  "type": null,
  "unit": null
}

Creates a new renewal intent.

Parameters

source_application required
The ID of the application this renewal intent is for.
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
no_renewal optional object

no_renewal.reason optional
The reason code why the renewal intent was not renewed. Can be affordability, circumstance_change, relocating, unit_issue or other.

no_renewal.reason_description optional
A description of why the renewal intent was not renewed.
renewal optional object

renewal.end_date optional
The end date of the renewal.

renewal.start_date optional
The start date of the renewal.
type optional
The type of renewal intent. Can be renewal or no_renewal.

Returns

Returns the x object if the request succeeded.

Retrieve a renewal intent

GET /v1/renewal_intents/:id

curl https://api.yorlet.com/v1/renewal_intents/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "ri_test",
  "object": "renewal_intent",
  "created": 1627210800,
  "application": null,
  "canceled_at": null,
  "completed_at": null,
  "source_application": "app_test",
  "status": "pending",
  "type": null,
  "unit": null
}

Retrieves the renewal intent with the given ID.

Parameters

No parameters

Returns

Returns a renewal intent object if a valid identifier was provided.

Update a renewal intent

POST /v1/renewal_intents/:id

curl https://api.yorlet.com/v1/renewal_intents/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "ri_test",
  "object": "renewal_intent",
  "created": 1627210800,
  "application": null,
  "canceled_at": null,
  "completed_at": null,
  "source_application": "app_test",
  "status": "pending",
  "type": null,
  "unit": null
}

Updates the specified renewal intent by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
no_renewal optional object

no_renewal.reason optional
The reason code why the renewal intent was not renewed. Can be affordability, circumstance_change, relocating, unit_issue or other.

no_renewal.reason_description optional
A description of why the renewal intent was not renewed.
renewal optional object

renewal.end_date optional
The end date of the renewal.

renewal.start_date optional
The start date of the renewal.
type optional
The type of renewal intent. Can be renewal or no_renewal.

Returns

Returns the renewal intent object if the update succeeded.

Cancel a renewal intent

POST /v1/renewal_intents/:id/cancel

curl https://api.yorlet.com/v1/renewal_intents/:id/cancel \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "ri_test",
  "object": "renewal_intent",
  "created": 1627210800,
  "application": null,
  "canceled_at": null,
  "completed_at": null,
  "source_application": "app_test",
  "status": "pending",
  "type": null,
  "unit": null
}

Permanently cancel a renewal intent. This cannot be undone.

Parameters

No parameters

Returns

Returns a canceled object on success. If the renewal intent ID does not exist, this call throws an error.

Complete a renewal intent

POST /v1/renewal_intents/:id/complete

curl https://api.yorlet.com/v1/renewal_intents/:id/complete \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "ri_test",
  "object": "renewal_intent",
  "created": 1627210800,
  "application": null,
  "canceled_at": null,
  "completed_at": null,
  "source_application": "app_test",
  "status": "pending",
  "type": null,
  "unit": null
}

Permanently complete a renewal intent. This cannot be undone.

Parameters

No parameters

Returns

Returns a completed object on success. If the renewal intent ID does not exist, this call throws an error.

List all renewal intents

GET /v1/renewal_intents

curl https://api.yorlet.com/v1/renewal_intents \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "ri_test",
      "object": "renewal_intent",
      "created": 1627210800,
      "application": null,
      "canceled_at": null,
      "completed_at": null,
      "source_application": "app_test",
      "status": "pending",
      "type": null,
      "unit": null
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of renewal intents. The renewal intents are returned sorted by creation date, with the most recent renewal intent appearing first.

Parameters

No parameters

Returns

A object with a data property that contains an array of renewal intents.

Units

Endpoints

POST    /v1/units
GET     /v1/units/:id
POST    /v1/units/:id
DELETE  /v1/units/:id
GET     /v1/units

Unit objects are a core resource. The API allows you to create, delete, and update your units. You can retrieve individual units as well as a list of all your units.

The unit object

The unit object

{
  "id": "unit_test",
  "object": "unit",
  "created": 1627210800,
  "active_tenancy": null,
  "active_tenancy_end": null,
  "archived": false,
  "archived_at": null,
  "available_from": null,
  "bathrooms": null,
  "bedrooms": null,
  "building": "build_test",
  "completion_date": null,
  "compliance": {
    "electric_safety_expires_at": null,
    "electric_safety": null,
    "epc_expires_at": null,
    "epc": null,
    "gas_safety_expires_at": null,
    "gas_safety": null,
    "gas_safety_required": true
  },
  "currency": "gbp",
  "currency_options": null,
  "default_deposit": null,
  "default_price": 150000,
  "description": null,
  "features": {},
  "fees": {
    "management_fee_discount": null,
    "management_fee_type": "percentage",
    "tax_behavior": "exclusive",
    "updated_at": null
  },
  "floor": null,
  "furnished": false,
  "has_owner": false,
  "maintenance_threshold": null,
  "management_type": null,
  "metadata": {},
  "name": "Apartment 101",
  "offline_reason": null,
  "owner_ids": [],
  "plot_number": null,
  "reference": null,
  "rent": {
    "default": 150000,
    "maximum": null,
    "minimum": null
  },
  "sales": {
    "last_purchase_price": null
  },
  "square_foot": null,
  "under_offer": false
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be unit.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
active_tenancy stringexpandable
The unit's active tenancy.
active_tenancy_end timestamp
The unit's active tenancy end date.
address object
The unit's address.
archived boolean
Whether the unit is archived.
archived_at timestamp
Time at which the unit was archived.
available_from timestamp
The date the unit is available from. Measured in seconds since the Unix epoch.
bathrooms integer
The number of bathrooms this unit has.
bedrooms integer
The number of bedrooms this unit has.
building stringexpandable
The ID of the building this unit is associated with.
completion_date timestamp
The date the unit was completed. Measured in seconds since the Unix epoch.
compliance object

compliance.electric_safety_expires_at integer
The date the unit’s electric safety certificate expires. Measured in seconds since the Unix epoch.

compliance.electric_safety string
(ID of a file upload) The unit’s electric safety certificate.

compliance.epc_expires_at integer
The date the unit’s EPC expires. Measured in seconds since the Unix epoch.

compliance.epc string
(ID of a file upload) The unit’s EPC.

compliance.gas_safety_expires_at integer
The date the unit’s gas safety certificate expires. Measured in seconds since the Unix epoch.

compliance.gas_safety string
(ID of a file upload) The unit’s gas safety certificate.

compliance.gas_safety_required boolean
Whether the unit requires a gas safety certificate.
contract_address string
The address that will be used when generating the contract.
currency string
Three-letter ISO currency code, in lowercase.
currency_options object
default_deposit integer
The unit's default deposit amount.
default_price integer
The unit's default price amount.
description string
An arbitrary string attached to the object. Often useful for displaying to users.
features object
The unit's features.
fees object
The unit fees.

fees.management_fee float
The default management fee percentage. Maximum decimal precision of 2.

fees.management_fee_amount integer
The default management fee fixed amount, represented as a whole integer in the smallest currency unit.

fees.management_fee_discount object
The default management fee discount.

fees.management_fee_discount.percent_off integer
The default management fee discount percent off.

fees.management_fee_type string
The management fee type. Can be percentage or fixed.

fees.renewal_fee integer
The default renewal fee, represented as a whole integer in the smallest currency unit.

fees.tax float
The default tax. Maximum decimal precision of 2.

fees.tax_behavior string
The tax behavior. Can be exclusive or inclusive.

fees.tenant_find_fee integer
The default tenant find fee, represented as a whole integer in the smallest currency unit.

fees.updated_at integer
The date the unit's fees were last updated. Measured in seconds since the Unix epoch.
floor integer
The unit's floor number.
furnished boolean
Whether the unit is furnished.
has_owner boolean
Whether the unit is owned by a third-party. This is true only if the unit has active unit owners.
maintenance_threshold integer
The threshold you are authorised to charge without the owners consent.
management_type string
The type of management the unit is under. Can be fully_managed or let_only.
metadata object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
name string
The unit's name.
offline_reason string
The reason the unit is offline.
owner_ids array
An array of the IDs of the unit's owners.
plot_number string
The unit's plot number.
reference string
An internal reference for the unit, useful for tracking units between mulitple systems.
rent object

rent.default integer
The default rental amount per month. Represented as a whole integer in the smallest currency unit.

rent.maximum integer
The maximum rental amount per month. Represented as a whole integer in the smallest currency unit.

rent.minimum integer
The minimum rental amount per month. Represented as a whole integer in the smallest currency unit.
sales object

sales.last_purchase_price integer
The last sale purchase price, useful for calculating yields. Represented as a whole integer in the smallest currency unit.
status string
The unit's status. Can be active, occupied, offline, maintenance or unmanaged.
square_foot integer
The unit's square foot.
under_offer boolean
Whether the unit is currently under offer.

Create a unit

POST /v1/units

curl https://api.yorlet.com/v1/units \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "unit_test",
  "object": "unit",
  "created": 1627210800,
  "active_tenancy": null,
  "active_tenancy_end": null,
  "archived": false,
  "archived_at": null,
  "available_from": null,
  "bathrooms": null,
  "bedrooms": null,
  "building": "build_test",
  "completion_date": null,
  "compliance": {
    "electric_safety_expires_at": null,
    "electric_safety": null,
    "epc_expires_at": null,
    "epc": null,
    "gas_safety_expires_at": null,
    "gas_safety": null,
    "gas_safety_required": true
  },
  "currency": "gbp",
  "currency_options": null,
  "default_deposit": null,
  "default_price": 150000,
  "description": null,
  "features": {},
  "fees": {
    "management_fee_discount": null,
    "management_fee_type": "percentage",
    "tax_behavior": "exclusive",
    "updated_at": null
  },
  "floor": null,
  "furnished": false,
  "has_owner": false,
  "maintenance_threshold": null,
  "management_type": null,
  "metadata": {},
  "name": "Apartment 101",
  "offline_reason": null,
  "owner_ids": [],
  "plot_number": null,
  "reference": null,
  "rent": {
    "default": 150000,
    "maximum": null,
    "minimum": null
  },
  "sales": {
    "last_purchase_price": null
  },
  "square_foot": null,
  "under_offer": false
}

Creates a unit.

Parameters

currency required
Three-letter ISO currency code, in lowercase. Must be a supported currency. Can be eur, gbp, sek or usd.
name required
The unit's name.
address optional object
The unit's address. Defaults to the associated building's address.

address.country required
Two-letter country code (ISO 3166-1 alpha-2).

address.line1 required
Address line 1 (e.g., street, PO Box, or company name).

address.city optional
City, district, suburb, town, or village.

address.line2 optional
Address line 2 (e.g., apartment, suite, unit, or building).

address.postal_code optional
Postal code.

address.state optional
State, county, province, or region.
alternate_postal_code optional
Some units in large multi-unit buildings have difference postcodes. You can supply an alternate postal code which overrides the default building postal code.
archived optional boolean
Whether the unit is archived.
available_from optional
The date the unit is available from.
bathrooms optional integer
The number of bathrooms.
bedrooms optional integer
The number of bedrooms.
building optional
The ID of the building this unit is in.
building_data optional object

building_data.address required object
The building's address.

building_data.address.country required
Two-letter country code (ISO 3166-1 alpha-2).

building_data.address.line1 required
Address line 1 (e.g., street, PO Box, or company name).

building_data.address.city optional
City, district, suburb, town, or village.

building_data.address.line2 optional
Address line 2 (e.g., apartment, suite, unit, or building).

building_data.address.postal_code optional
Postal code.

building_data.address.state optional
State, county, province, or region.

building_data.name required
The building's name.

building_data.accounting_code optional

building_data.active optional boolean

building_data.assignee optional

building_data.currency optional
The default currency for the building and any units associated with the building. Can be eur, gbp, sek or usd.

building_data.description optional

building_data.metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

building_data.single_unit optional boolean

building_data.type optional
Can be block_management, commercial, residential or student.

building_data.unit_fees optional object

building_data.unit_fees.management_fee optional number
The unit's management fee percentage amount.

building_data.unit_fees.management_fee_amount optional integer
The unit's management fee fixed amount.

building_data.unit_fees.management_fee_type optional
Can be percentage or fixed.

building_data.unit_fees.renewal_fee optional integer
The unit's renewal fee.

building_data.unit_fees.tax optional number
The tax to apply to the unit fees.

building_data.unit_fees.tax_behavior optional
Whether the tax is included or excluded from the fees. Can be inclusive or exclusive.

building_data.unit_fees.tenant_find_fee optional integer
The unit's tenant find fee.

building_data.workspace optional
completion_date optional
The date this unit completes.
compliance optional object

compliance.electric_safety optional
(ID of a file upload) The unit’s electric safety certificate.

compliance.electric_safety_expires_at optional
The date this unit’s electric safety certificate expires.

compliance.epc optional
(ID of a file upload) The unit’s EPC.

compliance.epc_expires_at optional
The date this unit's EPC expires.

compliance.gas_safety optional
(ID of a file upload) The unit’s gas safety certificate.

compliance.gas_safety_expires_at optional
The date this unit’s gas safety certificate expires.

compliance.gas_safety_required optional boolean

compliance.send_email optional boolean
Whether to send an email to the tenant.
contract_address optional
The contract address of the unit.
currency_options optional object
default_deposit optional integer
The default deposit amount to charge.
default_price optional integer
The default rental price per month.
features optional object

features.aspect optional
The unit's aspect. Can be n, s, e, w, ne, nw, se, sw or corner.

features.balcony optional boolean
Whether the unit has a balcony.

features.min_term optional
The minimum rental term.

features.pet_friendly optional boolean
Whether the unit is pet friendly.

features.view optional
fees optional object

fees.management_fee optional number
The unit's management fee percentage amount.

fees.management_fee_amount optional integer
The unit's management fee fixed amount.

fees.management_fee_discount optional object

fees.management_fee_discount.end optional
The date the discount ends.

fees.management_fee_discount.percent_off optional number
The discount percent to apply to the management fee.

fees.management_fee_type optional
Can be percentage or fixed.

fees.renewal_fee optional integer
The unit's renewal fee.

fees.send_update_email optional boolean
Whether to send an email to active unit owners with the updated fees.

fees.tax optional number
The tax to apply to the unit fees.

fees.tax_behavior optional
Whether the tax is included or excluded from the fees. Can be inclusive or exclusive.

fees.tenant_find_fee optional integer
The unit's tenant find fee.
floor optional integer
The unit's floor number.
furnished optional boolean
Whether the unit is furnished.
maintenance_threshold optional integer
The threshold you are authorised to charge without the owners consent.
management_type optional
The type of management. Can be fully_managed, let_only or rent_collection.
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
offline_reason optional
The reason the unit is offline.
owners optional array

owners.owner required

owners.assignee optional

owners.contract optional

owners.description optional

owners.follow_up optional

owners.metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

owners.negotiating_status optional
Can be contacted, no_details, not_likely, not_responding, ready_to_sign or undecided.

owners.percent_ownership optional number
plot_number optional
The unit's plot number.
reference optional
An internal reference for the unit, useful for tracking units between mulitple systems.
rent optional object

rent.default optional integer
The default rental amount per month.

rent.maximum optional integer
The maximum rental amount per month.

rent.minimum optional integer
The minimum rental amount per month.

rent.tax_percent optional number
The tax percent to apply to the rent.
sales optional object

sales.last_purchase_price optional integer
The unit's last purchase price.
square_foot optional number
The unit's square foot.
square_metre optional number
status optional
The unit's status. Can be available, offline, maintenance or unmanaged.

Returns

Returns the unit object if the request succeeded.

Retrieve a unit

GET /v1/units/:id

curl https://api.yorlet.com/v1/units/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "unit_test",
  "object": "unit",
  "created": 1627210800,
  "active_tenancy": null,
  "active_tenancy_end": null,
  "archived": false,
  "archived_at": null,
  "available_from": null,
  "bathrooms": null,
  "bedrooms": null,
  "building": "build_test",
  "completion_date": null,
  "compliance": {
    "electric_safety_expires_at": null,
    "electric_safety": null,
    "epc_expires_at": null,
    "epc": null,
    "gas_safety_expires_at": null,
    "gas_safety": null,
    "gas_safety_required": true
  },
  "currency": "gbp",
  "currency_options": null,
  "default_deposit": null,
  "default_price": 150000,
  "description": null,
  "features": {},
  "fees": {
    "management_fee_discount": null,
    "management_fee_type": "percentage",
    "tax_behavior": "exclusive",
    "updated_at": null
  },
  "floor": null,
  "furnished": false,
  "has_owner": false,
  "maintenance_threshold": null,
  "management_type": null,
  "metadata": {},
  "name": "Apartment 101",
  "offline_reason": null,
  "owner_ids": [],
  "plot_number": null,
  "reference": null,
  "rent": {
    "default": 150000,
    "maximum": null,
    "minimum": null
  },
  "sales": {
    "last_purchase_price": null
  },
  "square_foot": null,
  "under_offer": false
}

Retrieves the unit with the given ID.

Parameters

No parameters

Returns

Returns a unit object if a valid identifier was provided.

Update a unit

POST /v1/units/:id

curl https://api.yorlet.com/v1/units/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "unit_test",
  "object": "unit",
  "created": 1627210800,
  "active_tenancy": null,
  "active_tenancy_end": null,
  "archived": false,
  "archived_at": null,
  "available_from": null,
  "bathrooms": null,
  "bedrooms": null,
  "building": "build_test",
  "completion_date": null,
  "compliance": {
    "electric_safety_expires_at": null,
    "electric_safety": null,
    "epc_expires_at": null,
    "epc": null,
    "gas_safety_expires_at": null,
    "gas_safety": null,
    "gas_safety_required": true
  },
  "currency": "gbp",
  "currency_options": null,
  "default_deposit": null,
  "default_price": 150000,
  "description": null,
  "features": {},
  "fees": {
    "management_fee_discount": null,
    "management_fee_type": "percentage",
    "tax_behavior": "exclusive",
    "updated_at": null
  },
  "floor": null,
  "furnished": false,
  "has_owner": false,
  "maintenance_threshold": null,
  "management_type": null,
  "metadata": {},
  "name": "Apartment 101",
  "offline_reason": null,
  "owner_ids": [],
  "plot_number": null,
  "reference": null,
  "rent": {
    "default": 150000,
    "maximum": null,
    "minimum": null
  },
  "sales": {
    "last_purchase_price": null
  },
  "square_foot": null,
  "under_offer": false
}

Updates the specified unit by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

address optional object
The unit's address. Defaults to the associated building's address.

address.country required
Two-letter country code (ISO 3166-1 alpha-2).

address.line1 required
Address line 1 (e.g., street, PO Box, or company name).

address.city optional
City, district, suburb, town, or village.

address.line2 optional
Address line 2 (e.g., apartment, suite, unit, or building).

address.postal_code optional
Postal code.

address.state optional
State, county, province, or region.
alternate_postal_code optional
Some units in large multi-unit buildings have difference postcodes. You can supply an alternate postal code which overrides the default building postal code.
archived optional boolean
Whether the unit is archived.
available_from optional
The date the unit is available from.
bathrooms optional integer
The number of bathrooms.
bedrooms optional integer
The number of bedrooms.
completion_date optional
The date this unit completes.
compliance optional object

compliance.electric_safety optional
(ID of a file upload) The unit’s electric safety certificate.

compliance.electric_safety_expires_at optional
The date this unit’s electric safety certificate expires.

compliance.epc optional
(ID of a file upload) The unit’s EPC.

compliance.epc_expires_at optional
The date this unit's EPC expires.

compliance.gas_safety optional
(ID of a file upload) The unit’s gas safety certificate.

compliance.gas_safety_expires_at optional
The date this unit’s gas safety certificate expires.

compliance.gas_safety_required optional boolean

compliance.send_email optional boolean
Whether to send an email to the tenant.
contract_address optional
The contract address of the unit.
currency_options optional object
default_deposit optional integer
The default deposit amount to charge.
default_price optional integer
The default rental price per month.
features optional object

features.aspect optional
The unit's aspect. Can be n, s, e, w, ne, nw, se, sw or corner.

features.balcony optional boolean
Whether the unit has a balcony.

features.min_term optional
The minimum rental term.

features.pet_friendly optional boolean
Whether the unit is pet friendly.

features.view optional
fees optional object

fees.management_fee optional number
The unit's management fee percentage amount.

fees.management_fee_amount optional integer
The unit's management fee fixed amount.

fees.management_fee_discount optional object

fees.management_fee_discount.end optional
The date the discount ends.

fees.management_fee_discount.percent_off optional number
The discount percent to apply to the management fee.

fees.management_fee_type optional
Can be percentage or fixed.

fees.renewal_fee optional integer
The unit's renewal fee.

fees.send_update_email optional boolean
Whether to send an email to active unit owners with the updated fees.

fees.tax optional number
The tax to apply to the unit fees.

fees.tax_behavior optional
Whether the tax is included or excluded from the fees. Can be inclusive or exclusive.

fees.tenant_find_fee optional integer
The unit's tenant find fee.
floor optional integer
The unit's floor number.
furnished optional boolean
Whether the unit is furnished.
maintenance_threshold optional integer
The threshold you are authorised to charge without the owners consent.
management_type optional
The type of management. Can be fully_managed, let_only or rent_collection.
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
name optional
The unit's name.
offline_reason optional
The reason the unit is offline.
owners optional array

owners.owner required

owners.assignee optional

owners.contract optional

owners.description optional

owners.follow_up optional

owners.metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

owners.negotiating_status optional
Can be contacted, no_details, not_likely, not_responding, ready_to_sign or undecided.

owners.percent_ownership optional number
ownership_ended_at optional
The date the current unit ownership ended.
plot_number optional
The unit's plot number.
reference optional
An internal reference for the unit, useful for tracking units between mulitple systems.
rent optional object

rent.default optional integer
The default rental amount per month.

rent.maximum optional integer
The maximum rental amount per month.

rent.minimum optional integer
The minimum rental amount per month.

rent.tax_percent optional number
The tax percent to apply to the rent.
sales optional object

sales.last_purchase_price optional integer
The unit's last purchase price.
square_foot optional number
The unit's square foot.
square_metre optional number
status optional
The unit's status. Can be available, offline, maintenance or unmanaged.

Returns

Returns the unit object if the update succeeded.

Delete a unit

DELETE /v1/units/:id

curl https://api.yorlet.com/v1/units/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "unit_test",
  "object": "unit",
  "deleted": true
}

Permanently deletes a unit. This cannot be undone.

Parameters

No parameters

Returns

Returns an object with a deleted parameter on success. If the unit ID does not exist, this call throws an error.

List all units

GET /v1/units

curl https://api.yorlet.com/v1/units \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "unit_test",
      "object": "unit",
      "created": 1627210800,
      "active_tenancy": null,
      "active_tenancy_end": null,
      "archived": false,
      "archived_at": null,
      "available_from": null,
      "bathrooms": null,
      "bedrooms": null,
      "building": "build_test",
      "completion_date": null,
      "compliance": {
        "electric_safety_expires_at": null,
        "electric_safety": null,
        "epc_expires_at": null,
        "epc": null,
        "gas_safety_expires_at": null,
        "gas_safety": null,
        "gas_safety_required": true
      },
      "currency": "gbp",
      "currency_options": null,
      "default_deposit": null,
      "default_price": 150000,
      "description": null,
      "features": {},
      "fees": {
        "management_fee_discount": null,
        "management_fee_type": "percentage",
        "tax_behavior": "exclusive",
        "updated_at": null
      },
      "floor": null,
      "furnished": false,
      "has_owner": false,
      "maintenance_threshold": null,
      "management_type": null,
      "metadata": {},
      "name": "Apartment 101",
      "offline_reason": null,
      "owner_ids": [],
      "plot_number": null,
      "reference": null,
      "rent": {
        "default": 150000,
        "maximum": null,
        "minimum": null
      },
      "sales": {
        "last_purchase_price": null
      },
      "square_foot": null,
      "under_offer": false
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of units. The units are returned sorted by creation date, with the most recent units appearing first.

Parameters

No parameters

Returns

A object with a data property that contains an array of units.

Payments Resources

Balance

Endpoints

GET     /v1/balance
GET     /v1/balance/owners

The balance object

The balance object

{
  "object": "balance",
  "available": [
    {
      "amount": 19592,
      "currency": "gbp"
    }
  ],
  "in_transit": [
    {
      "amount": 0,
      "currency": "gbp"
    }
  ],
  "pending": [
    {
      "amount": -19592,
      "currency": "gbp"
    }
  ],
  "treasury": {
    "available": [
      {
        "amount": 5140000,
        "currency": "gbp"
      }
    ],
    "in_transit": [
      {
        "amount": 0,
        "currency": "gbp"
      }
    ],
    "pending": [
      {
        "amount": 0,
        "currency": "gbp"
      }
    ]
  }
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be balance.
available array
in_transit array
pending array
treasury array

Retrieve balance

GET /v1/balance

curl https://api.yorlet.com/v1/balance \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "balance",
  "available": [
    {
      "amount": 19592,
      "currency": "gbp"
    }
  ],
  "in_transit": [
    {
      "amount": 0,
      "currency": "gbp"
    }
  ],
  "pending": [
    {
      "amount": -19592,
      "currency": "gbp"
    }
  ],
  "treasury": {
    "available": [
      {
        "amount": 5140000,
        "currency": "gbp"
      }
    ],
    "in_transit": [
      {
        "amount": 0,
        "currency": "gbp"
      }
    ],
    "pending": [
      {
        "amount": 0,
        "currency": "gbp"
      }
    ]
  }
}

Parameters

No parameters

Returns

Returns balance object.

Retrieve owner balance

GET /v1/balance/owners

curl https://api.yorlet.com/v1/balance/owners \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "balance",
  "available": [
    {
      "amount": 19592,
      "currency": "gbp"
    }
  ],
  "in_transit": [
    {
      "amount": 0,
      "currency": "gbp"
    }
  ],
  "pending": [
    {
      "amount": -19592,
      "currency": "gbp"
    }
  ],
  "treasury": {
    "available": [
      {
        "amount": 5140000,
        "currency": "gbp"
      }
    ],
    "in_transit": [
      {
        "amount": 0,
        "currency": "gbp"
      }
    ],
    "pending": [
      {
        "amount": 0,
        "currency": "gbp"
      }
    ]
  }
}

Parameters

No parameters

Returns

Returns owner balance object.

Balance Transactions

Endpoints

GET     /v1/balance_transactions

The balance transaction object

The balance transaction object

{
  "id": "btxn_test",
  "object": "balance_transaction",
  "created": 1627210800,
  "amount": 10000,
  "available_on": null,
  "fee": 1000,
  "fee_details": [],
  "net": 9000,
  "payout": null,
  "source_object": null,
  "source": null,
  "status": null,
  "type": "payment"
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be balance_transaction.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
amount integer
available_on timestamp
The time at which the balance transaction will become available.
currency string
description string
fee integer
fee_details array
net integer
payout string
source_object string
source string
status string
type string

List all balance transactions

GET /v1/balance_transactions

curl https://api.yorlet.com/v1/balance_transactions \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "btxn_test",
      "object": "balance_transaction",
      "created": 1627210800,
      "amount": 10000,
      "available_on": null,
      "fee": 1000,
      "fee_details": [],
      "net": 9000,
      "payout": null,
      "source_object": null,
      "source": null,
      "status": null,
      "type": "payment"
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

List

Payment Initiations (beta)

Endpoints

POST    /v1/payment_initiations
GET     /v1/payment_initiations/:id
POST    /v1/payment_initiations/:id/tokens
GET     /v1/payment_initiations

Payment Initiations allow you to initiate a payment from a bank account with Open Banking. Yorlet supports Payment Initiation using Plaid.

The payment initiation object

The payment initiation object

{
  "id": "py_init_test",
  "object": "payment_initiation",
  "created": 1627210800,
  "amount": 40000,
  "currency": "gbp",
  "customer": "cus_l34bx7zoNY2w1tv8",
  "external_account": null,
  "failure_code": null,
  "failure_message": null,
  "invoice": null,
  "payment_method": "pm_l34dl7phkOVU7wcI",
  "reconciliation": null,
  "reference": "REF001",
  "status": "requires_action",
  "type": "customer_payment"
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be payment_initiation.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
amount integer
Amount intended to be collected by this payment. This must be a positive integer in the smallest currency unit (e.g., 100 pennies for a charge of £1.00).
currency string
Three-letter ISO currency code, in lowercase. Must be a supported currency.
customer string
ID of the customer this payment initiation belongs to.
external_account stringexpandable
ID of the external account this payment initiation belongs to, if one exists.
failure_code string
The failure code for the payment initiation.
failure_message string
The reason for the payment initiation failure, if one exists.
invoice string
ID of the invoice this payment initiation belongs to, if one exists.
payment_method string
ID of the payment method this payment initiation belongs to, if one exists.
reconciliation object
The reconciliation options for this payment initiation.

reconciliation.type string
The type of reconciliation for this payment initiation. Can be application or invoice.

reconciliation.application object
The application reconciliation details for this payment initiation.

reconciliation.application.id string
The ID of the application to reconcile for.

reconciliation.application.payment_type string
The application payment type to reconcile for. Can be holding_fee, deposit or advance_rent.

reconciliation.invoice object
The invoice reconciliation details for this payment initiation.

reconciliation.invoice.id string
The ID of the invoice to reconcile for.
reference string
A reference for the payment. This should not contain special characters since not all institutions support them.
status undefined
The status of the payment initiation. Can be requires_action, processing, succeeded, failed or unknown.
type undefined
The type of the payment initiation. Can be account_payment or customer_payment.

The payment initiation token object

The payment initiation object

{
  "object": "payment_initiation_token",
  "token": "link-33792986-2b9c-4b80-b1f2-518caaac6183",
  "type": "plaid"
}

Attributes

object string
String representing the object's type. Objects of the same type share the same value. Can be payment_initiation_token.
token string
The token to be used with the Plaid API to initiate a payment.
type undefined
The type of token. Can be plaid.

Create a payment initiation

POST /v1/payment_initiations

curl https://api.yorlet.com/v1/payment_initiations \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "py_init_test",
  "object": "payment_initiation",
  "created": 1627210800,
  "amount": 40000,
  "currency": "gbp",
  "customer": "cus_l34bx7zoNY2w1tv8",
  "external_account": null,
  "failure_code": null,
  "failure_message": null,
  "invoice": null,
  "payment_method": "pm_l34dl7phkOVU7wcI",
  "reconciliation": null,
  "reference": "REF001",
  "status": "requires_action",
  "type": "customer_payment"
}

Create a payment initiation request. Yorlet supports two types of payment initiation: type=inbound_payment initiates a payment from a bank account to your account’s bank account, and type=outbound_payment initiates a payment from your bank account to the supplied customer’s bank transfer payment method.

Parameters

amount required integer
The amount to charge. Should be a positive integer in the smallest currency unit (e.g. 100 for £1.00).
currency required
Three-letter ISO currency code, in lowercase. Must be a supported currency. Can be gbp or sek.
type required
The type of payment initiation. Can be inbound_payment or outbound_payment.
inbound_payment optional object

inbound_payment.type required
The type of payment initiation. Can be funding_instruction.

inbound_payment.funding_instruction optional
The ID of the funding instruction this payment initiation belongs to. Only allowed for funding_instruction_payment type.
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
outbound_payment optional object
The outbound payment hash. Required for outbound_payment type.

outbound_payment.type required
The type of payment initiation. Can be owner_payout.

outbound_payment.owner_payout optional
The ID of the owner payout this payment initiation belongs to. Only allowed for owner_payout type.
reference optional
The reference for this payment initiation. This must be an alphanumeric string with at most 18 characters and must not contain any special characters (since not all institutions support them).

Returns

Returns the payment initiation object if the request succeeded.

Retrieves a payment initiation token

GET /v1/payment_initiations/:id

curl https://api.yorlet.com/v1/payment_initiations/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "payment_initiation_token",
  "token": "link-33792986-2b9c-4b80-b1f2-518caaac6183",
  "type": "plaid"
}

Retrieves a Payment Initiation.

Parameters

No parameters

Returns

The single-use token object is returned upon success. Otherwise, this call returns an error.

Create a payment initiation token

POST /v1/payment_initiations/:id/tokens

curl https://api.yorlet.com/v1/payment_initiations/:id/tokens \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "object": "payment_initiation_token",
  "token": "link-33792986-2b9c-4b80-b1f2-518caaac6183",
  "type": "plaid"
}

Creates a single-use token that can be used to initiate a payment. Yorlet supports Payment Initiation using Plaid, you will need to launch the Payment Initiation flow in Plaid Link with the token returned by this endpoint.

Parameters

brand_name optional
The name you wish to display to users in Plaid Link. Maximum length of 30 characters.

Returns

The single-use token object is returned upon success. Otherwise, this call returns an error.

List all payment initiations

GET /v1/payment_initiations

curl https://api.yorlet.com/v1/payment_initiations \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "py_init_test",
      "object": "payment_initiation",
      "created": 1627210800,
      "amount": 40000,
      "currency": "gbp",
      "customer": "cus_l34bx7zoNY2w1tv8",
      "external_account": null,
      "failure_code": null,
      "failure_message": null,
      "invoice": null,
      "payment_method": "pm_l34dl7phkOVU7wcI",
      "reconciliation": null,
      "reference": "REF001",
      "status": "requires_action",
      "type": "customer_payment"
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of your payment initiations. The payment initiations are returned sorted by creation date, with the most recently created payment initiations appearing first.

Parameters

No parameters

Returns

A object with a data property that contains an array of payment initiations.

Payment Sessions

Endpoints

POST    /v1/payment_sessions
GET     /v1/payment_sessions/:id
POST    /v1/payment_sessions/:id/cancel
GET     /v1/payment_sessions

To create an payment session, you create a payment session object.

The payment session object

The payment session object

{
  "id": "py_sess_test",
  "object": "payment_session",
  "created": 1627210800,
  "amount": 100000,
  "currency": "gbp",
  "customer": "cus_test",
  "description": null,
  "metadata": {},
  "mode": "payment",
  "payment_method_types": [
    "card"
  ],
  "reporting_type": "deposit",
  "return_url": null,
  "status": "succeeded",
  "transaction": null,
  "url": "https://pay.yorlet.com/session/py_sess_test"
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be payment_session.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
amount integer
The transaction amount, which will be reflected in your balance. This amount is in your currency and in the smallest currency unit.
currency string
Three-letter ISO currency code, in lowercase. Must be a supported currency.
customer stringexpandable
ID of the customer associated with this transaction.
description string
An arbitrary string attached to the object. Often useful for displaying to users.
metadata object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
mode object
The payment session mode. Can be payment.
payment_method_types array
The payment method types allowed to be used to create the transaction.
reporting_type string
The reporting type.
return_url string
The url to redirect the customer to after the payment completes.
status string
The transactions status of the payment session. Can be paid or unpaid.
transaction stringexpandable
The transaction ID for the payment session.
url string
The URL to redirect the user to complete the payment session.

Create a payment session

POST /v1/payment_sessions

curl https://api.yorlet.com/v1/payment_sessions \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{
  "amount": 100000,
  "currency": "gbp",
  "customer": "cus_test",
  "mode": "payment",
  "payment_method_types": [
    "card"
  ]
}'

Example Response

{
  "id": "py_sess_test",
  "object": "payment_session",
  "created": 1627210800,
  "amount": 100000,
  "currency": "gbp",
  "customer": "cus_test",
  "description": null,
  "metadata": {},
  "mode": "payment",
  "payment_method_types": [
    "card"
  ],
  "reporting_type": "deposit",
  "return_url": null,
  "status": "succeeded",
  "transaction": null,
  "url": "https://pay.yorlet.com/session/py_sess_test"
}

Creates a new payment session.

Parameters

amount required integer
The amount to charge. Should be a positive integer in the smallest currency unit (e.g. 100 for £1.00).
currency required
Three-letter ISO currency code, in lowercase. Must be a supported currency. Can be eur, gbp, sek or usd.
customer required
The ID of the customer the transaction is for.
mode required
Can be payment.
payment_method_types required array
Can be autogiro, bacs_debit, bank_transfer, card, direct_transfer, pay_by_bank or sepa_debit.
description optional
An arbitrary string attached to the object. Often useful for displaying to users.
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
payment_method_options optional object
Payment method configuration options.
reporting_type optional
The reporting type of the transaction. Defaults to charge. Can be advance_rent, charge, deposit, holding_fee or rent.
return_url optional
The URL to redirect the user to after the transaction is complete.
send_email optional boolean
Send the URL to the customer email address.
statement_descriptor optional
The statement descriptor that will appear on customers bank statement.
transaction_data optional object
A subset of parameters to be passed to transaction creation.

transaction_data.customer_balance optional object
A hash containing information about the customer balance options.

transaction_data.customer_balance.apply optional boolean
Whether to apply the transaction amount to the customer’s balance.

transaction_data.customer_balance.description optional
A description of the transaction to be applied to the customer’s balance.

transaction_data.transfer_data optional object

transaction_data.transfer_data.use_unit_ownership optional boolean
If a unit ID is supplied, transfers will be created based on the unit's ownership.

transaction_data.unit optional
The ID of the unit.

Returns

Returns the payment session object if the request succeeded.

Retrieve a payment session

GET /v1/payment_sessions/:id

curl https://api.yorlet.com/v1/payment_sessions/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "py_sess_test",
  "object": "payment_session",
  "created": 1627210800,
  "amount": 100000,
  "currency": "gbp",
  "customer": "cus_test",
  "description": null,
  "metadata": {},
  "mode": "payment",
  "payment_method_types": [
    "card"
  ],
  "reporting_type": "deposit",
  "return_url": null,
  "status": "succeeded",
  "transaction": null,
  "url": "https://pay.yorlet.com/session/py_sess_test"
}

Retrieves the payment session with the given ID.

Parameters

No parameters

Returns

Returns a payment session object if a valid identifier was provided.

Cancel a payment session

POST /v1/payment_sessions/:id/cancel

curl https://api.yorlet.com/v1/payment_sessions/:id/cancel \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "py_sess_test",
  "object": "payment_session",
  "created": 1627210800,
  "amount": 100000,
  "currency": "gbp",
  "customer": "cus_test",
  "description": null,
  "metadata": {},
  "mode": "payment",
  "payment_method_types": [
    "card"
  ],
  "reporting_type": "deposit",
  "return_url": null,
  "status": "succeeded",
  "transaction": null,
  "url": "https://pay.yorlet.com/session/py_sess_test"
}

Cancels the payment session with the given ID.

Parameters

No parameters

Returns

Returns a canceled payment session object if a valid identifier was provided.

List all payment sessions

GET /v1/payment_sessions

curl https://api.yorlet.com/v1/payment_sessions \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "py_sess_test",
      "object": "payment_session",
      "created": 1627210800,
      "amount": 100000,
      "currency": "gbp",
      "customer": "cus_test",
      "description": null,
      "metadata": {},
      "mode": "payment",
      "payment_method_types": [
        "card"
      ],
      "reporting_type": "deposit",
      "return_url": null,
      "status": "succeeded",
      "transaction": null,
      "url": "https://pay.yorlet.com/session/py_sess_test"
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of payment sessions. The payment sessions are returned sorted by creation date, with the most recent payment sessions appearing first.

Parameters

No parameters

Returns

A object with a data property that contains an array of payment sessions.

Transactions

Endpoints

POST    /v1/transactions
GET     /v1/transactions/:id
POST    /v1/transactions/:id
POST    /v1/transactions/:id/capture
POST    /v1/transactions/:id/confirm
POST    /v1/transactions/:id/cancel
POST    /v1/transactions/:id/resend_receipt
GET     /v1/transactions

The API allows you to retrieve and list transactions.

The transaction object

The transaction object

{
  "id": "txn_test",
  "object": "transaction",
  "created": 1627210800,
  "amount": 100000,
  "amount_refunded": 0,
  "application": null,
  "balance_transaction": null,
  "capture_method": null,
  "confirmed_at": null,
  "cross_border": {
    "amount": null,
    "enabled": false
  },
  "currency_conversion": null,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "dispute": null,
  "disputed": false,
  "invoice": null,
  "last_payment_error": null,
  "metadata": {},
  "next_action": null,
  "owner_payout": null,
  "paid_at": null,
  "payment_method": null,
  "payment_method_types": [],
  "payment_session": null,
  "processing": null,
  "refunded": false,
  "reporting_type": "deposit",
  "status": "succeeded",
  "transfer": null,
  "transfer_data": {
    "transfers": null,
    "use_unit_ownership": false
  },
  "transfer_group": null
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be transaction.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
amount integer
The transaction amount, which will be reflected in your balance. This amount is in your currency and in the smallest currency unit.
amount_refunded integer
The amount refunded.
application string
ID of the application associated with this transaction.
balance_transaction stringexpandable
ID of the balance transaction associated with this transaction.
capture_method string
The capture method for this transaction. Can be automatic or manual.
confirmed_at timestamp
Time at which the transaction was confirmed. Measured in seconds since the Unix epoch.
cross_border array
The cross border payment data.
currency_conversion object
The currency conversion data.
currency string
Three-letter ISO currency code, in lowercase. Must be a supported currency.
customer stringexpandable
ID of the customer associated with this transaction.
description string
An arbitrary string attached to the object. Often useful for displaying to users.
dispute stringexpandable
If the transaction ha been disputed, the ID of the dispute.
disputed boolean
Boolean value to indicate whether transaction has been disputed or not.
invoice stringexpandable
ID of the invoice associated with this transaction.
last_payment_error object
An object containing, if any, the last error the occured when attempting this payment.
metadata object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
next_action object
An object with the next actions to take to complete the payment.
owner_payout stringexpandable
ID of the owner payout associated with this transaction.
paid_at timestamp
Time at which the transaction was paid. Measured in seconds since the Unix epoch.
payment_method stringexpandable
Payment method for the transaction. It must belong to the customer associated with the transaction.
payment_method_types array
The payment method types allowed to be used to create the transaction.
payment_session stringexpandable
Payment session for the transaction.
processing object
If present, this property tells you about the processing state of the payment.
refunded boolean
Boolean value to indicate whether funds has been refunded or not.
reporting_type string
The reporting type.
status string
The transactions status. Can be requires_payment_method, requires_confirmation, requires_action, processing, canceled or succeeded.
transfer string
The transfer ID for the transaction.
transfer_data object
The data with which to automatically create a Transfer when the transaction is paid.
transfer_group string
The transfer group for the transaction.

Create a transaction

POST /v1/transactions

curl https://api.yorlet.com/v1/transactions \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "txn_test",
  "object": "transaction",
  "created": 1627210800,
  "amount": 100000,
  "amount_refunded": 0,
  "application": null,
  "balance_transaction": null,
  "capture_method": null,
  "confirmed_at": null,
  "cross_border": {
    "amount": null,
    "enabled": false
  },
  "currency_conversion": null,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "dispute": null,
  "disputed": false,
  "invoice": null,
  "last_payment_error": null,
  "metadata": {},
  "next_action": null,
  "owner_payout": null,
  "paid_at": null,
  "payment_method": null,
  "payment_method_types": [],
  "payment_session": null,
  "processing": null,
  "refunded": false,
  "reporting_type": "deposit",
  "status": "succeeded",
  "transfer": null,
  "transfer_data": {
    "transfers": null,
    "use_unit_ownership": false
  },
  "transfer_group": null
}

Creates a transaction.

Parameters

customer required
The ID of the customer the transaction is for.
payment_method_types required array
Can be autogiro, bacs_debit, card, card_present, bank_transfer, direct_transfer, gbp_credit_transfer, pay_by_bank or sepa_debit.
amount optional integer
The amount to charge. Should be a positive integer in the smallest currency unit (e.g. 100 for £1.00). The amount is required if you do not supply an application and application_payment_type.
application optional
The ID of the application the transaction is for.
application_payment_type optional
The application payment type. Only allowed if the supplied application is open. Can be advance_rent, deposit or holding_fee.
capture_method optional
Can be automatic or manual.
confirm optional boolean
currency optional
Three-letter ISO currency code, in lowercase. Must be a supported currency. Can be eur, gbp, sek or usd.
customer_balance optional object
A hash containing information about the customer balance options.

customer_balance.apply optional boolean
Whether to apply the transaction amount to the customer’s balance.

customer_balance.description optional
A description of the transaction to be applied to the customer’s balance.
description optional
An arbitrary string attached to the object. Often useful for displaying to users.
invoice optional
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
off_session optional boolean
payment_method optional
reporting_type optional
The reporting type of the transaction. Only allowed if you don't supply an application ID. Can be advance_rent, charge, deposit or holding_fee.
return_url optional
The URL to redirect the user to if the transaction requires additional action to complete.
send_receipt_email optional boolean
statement_descriptor optional
The statement descriptor that will appear on customers bank statement. Only allowed if you don't supply an application payment type.
transfer_data optional object

transfer_data.use_unit_ownership optional boolean
If a unit ID is supplied, transfers will be created based on the unit's ownership.
unit optional
The ID of the unit. Only allowed if you don't supply an application ID.

Returns

Returns a transaction object if successful.

Retrieve a transaction

GET /v1/transactions/:id

curl https://api.yorlet.com/v1/transactions/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "txn_test",
  "object": "transaction",
  "created": 1627210800,
  "amount": 100000,
  "amount_refunded": 0,
  "application": null,
  "balance_transaction": null,
  "capture_method": null,
  "confirmed_at": null,
  "cross_border": {
    "amount": null,
    "enabled": false
  },
  "currency_conversion": null,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "dispute": null,
  "disputed": false,
  "invoice": null,
  "last_payment_error": null,
  "metadata": {},
  "next_action": null,
  "owner_payout": null,
  "paid_at": null,
  "payment_method": null,
  "payment_method_types": [],
  "payment_session": null,
  "processing": null,
  "refunded": false,
  "reporting_type": "deposit",
  "status": "succeeded",
  "transfer": null,
  "transfer_data": {
    "transfers": null,
    "use_unit_ownership": false
  },
  "transfer_group": null
}

Retrieves the transaction with the given ID.

Parameters

No parameters

Returns

Returns a transaction object if a valid identifier was provided.

Update a transaction

POST /v1/transactions/:id

curl https://api.yorlet.com/v1/transactions/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "txn_test",
  "object": "transaction",
  "created": 1627210800,
  "amount": 100000,
  "amount_refunded": 0,
  "application": null,
  "balance_transaction": null,
  "capture_method": null,
  "confirmed_at": null,
  "cross_border": {
    "amount": null,
    "enabled": false
  },
  "currency_conversion": null,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "dispute": null,
  "disputed": false,
  "invoice": null,
  "last_payment_error": null,
  "metadata": {},
  "next_action": null,
  "owner_payout": null,
  "paid_at": null,
  "payment_method": null,
  "payment_method_types": [],
  "payment_session": null,
  "processing": null,
  "refunded": false,
  "reporting_type": "deposit",
  "status": "succeeded",
  "transfer": null,
  "transfer_data": {
    "transfers": null,
    "use_unit_ownership": false
  },
  "transfer_group": null
}

Updates the transaction with the given ID.

Parameters

description optional
An arbitrary string attached to the object. Often useful for displaying to users.
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
payment_method_types optional array
Can be autogiro, bacs_debit, card, card_present, bank_transfer, direct_transfer, gbp_credit_transfer, pay_by_bank or sepa_debit.

Returns

Returns the updated transaction object if a valid identifier was provided.

Capture a transaction

POST /v1/transactions/:id/capture

curl https://api.yorlet.com/v1/transactions/:id/capture \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "txn_test",
  "object": "transaction",
  "created": 1627210800,
  "amount": 100000,
  "amount_refunded": 0,
  "application": null,
  "balance_transaction": null,
  "capture_method": null,
  "confirmed_at": null,
  "cross_border": {
    "amount": null,
    "enabled": false
  },
  "currency_conversion": null,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "dispute": null,
  "disputed": false,
  "invoice": null,
  "last_payment_error": null,
  "metadata": {},
  "next_action": null,
  "owner_payout": null,
  "paid_at": null,
  "payment_method": null,
  "payment_method_types": [],
  "payment_session": null,
  "processing": null,
  "refunded": false,
  "reporting_type": "deposit",
  "status": "succeeded",
  "transfer": null,
  "transfer_data": {
    "transfers": null,
    "use_unit_ownership": false
  },
  "transfer_group": null
}

Captures the transaction.

Parameters

Returns

Returns a transaction object if successful.

Confirm a transaction

POST /v1/transactions/:id/confirm

curl https://api.yorlet.com/v1/transactions/:id/confirm \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "txn_test",
  "object": "transaction",
  "created": 1627210800,
  "amount": 100000,
  "amount_refunded": 0,
  "application": null,
  "balance_transaction": null,
  "capture_method": null,
  "confirmed_at": null,
  "cross_border": {
    "amount": null,
    "enabled": false
  },
  "currency_conversion": null,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "dispute": null,
  "disputed": false,
  "invoice": null,
  "last_payment_error": null,
  "metadata": {},
  "next_action": null,
  "owner_payout": null,
  "paid_at": null,
  "payment_method": null,
  "payment_method_types": [],
  "payment_session": null,
  "processing": null,
  "refunded": false,
  "reporting_type": "deposit",
  "status": "succeeded",
  "transfer": null,
  "transfer_data": {
    "transfers": null,
    "use_unit_ownership": false
  },
  "transfer_group": null
}

Confirms the transaction.

Parameters

off_session optional boolean
payment_method optional
payment_method_types optional array
Can be autogiro, bacs_debit, card, card_present, bank_transfer, direct_transfer, gbp_credit_transfer, pay_by_bank or sepa_debit.
return_url optional

Returns

Returns a transaction object if successful.

Cancel a transaction

POST /v1/transactions/:id/cancel

curl https://api.yorlet.com/v1/transactions/:id/cancel \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "txn_test",
  "object": "transaction",
  "created": 1627210800,
  "amount": 100000,
  "amount_refunded": 0,
  "application": null,
  "balance_transaction": null,
  "capture_method": null,
  "confirmed_at": null,
  "cross_border": {
    "amount": null,
    "enabled": false
  },
  "currency_conversion": null,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "dispute": null,
  "disputed": false,
  "invoice": null,
  "last_payment_error": null,
  "metadata": {},
  "next_action": null,
  "owner_payout": null,
  "paid_at": null,
  "payment_method": null,
  "payment_method_types": [],
  "payment_session": null,
  "processing": null,
  "refunded": false,
  "reporting_type": "deposit",
  "status": "succeeded",
  "transfer": null,
  "transfer_data": {
    "transfers": null,
    "use_unit_ownership": false
  },
  "transfer_group": null
}

Cancels the transaction.

Parameters

No parameters

Returns

Returns a transaction object if successful.

Resend a transaction receipt

POST /v1/transactions/:id/resend_receipt

curl https://api.yorlet.com/v1/transactions/:id/resend_receipt \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "txn_test",
  "object": "transaction",
  "created": 1627210800,
  "amount": 100000,
  "amount_refunded": 0,
  "application": null,
  "balance_transaction": null,
  "capture_method": null,
  "confirmed_at": null,
  "cross_border": {
    "amount": null,
    "enabled": false
  },
  "currency_conversion": null,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "dispute": null,
  "disputed": false,
  "invoice": null,
  "last_payment_error": null,
  "metadata": {},
  "next_action": null,
  "owner_payout": null,
  "paid_at": null,
  "payment_method": null,
  "payment_method_types": [],
  "payment_session": null,
  "processing": null,
  "refunded": false,
  "reporting_type": "deposit",
  "status": "succeeded",
  "transfer": null,
  "transfer_data": {
    "transfers": null,
    "use_unit_ownership": false
  },
  "transfer_group": null
}

Resends the transaction receipt.

Parameters

No parameters

Returns

Returns a transaction object if successful.

List all transactions

GET /v1/transactions

curl https://api.yorlet.com/v1/transactions \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "txn_test",
      "object": "transaction",
      "created": 1627210800,
      "amount": 100000,
      "amount_refunded": 0,
      "application": null,
      "balance_transaction": null,
      "capture_method": null,
      "confirmed_at": null,
      "cross_border": {
        "amount": null,
        "enabled": false
      },
      "currency_conversion": null,
      "currency": "gbp",
      "customer": null,
      "description": null,
      "dispute": null,
      "disputed": false,
      "invoice": null,
      "last_payment_error": null,
      "metadata": {},
      "next_action": null,
      "owner_payout": null,
      "paid_at": null,
      "payment_method": null,
      "payment_method_types": [],
      "payment_session": null,
      "processing": null,
      "refunded": false,
      "reporting_type": "deposit",
      "status": "succeeded",
      "transfer": null,
      "transfer_data": {
        "transfers": null,
        "use_unit_ownership": false
      },
      "transfer_group": null
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of transactions. The transactions are returned sorted by creation date, with the most recent transactions appearing first.

Parameters

No parameters

Returns

A object with a data property that contains an array of transactions.

Payment Methods Resources

External Accounts

Endpoints

POST    /v1/external_accounts
GET     /v1/external_accounts/:id
POST    /v1/external_accounts/:id
DELETE  /v1/external_accounts/:id
GET     /v1/external_accounts

External Accounts are transfer destinations for your Account or Owner objects. They can be bank accounts.

The external account object

The external account object

{
  "id": "ext_acct_test",
  "object": "external_account",
  "created": 1627210800,
  "available_payout_methods": [],
  "bank_account": {
    "account_holder_name": "Jane Doe",
    "account_holder_type": "individual",
    "bank_name": null,
    "country": "GB",
    "currency": "gbp",
    "last4": "1234",
    "routing_number": "101010",
    "swift_bic": null
  },
  "metadata": {},
  "status": "new",
  "type": "bank_account"
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be external_account.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
available_payout_methods array
The available payout methods for this external account.
bank_account object
The bank account details.

bank_account.account_holder_name string
The name of the account holder.

bank_account.account_holder_type string
The type of account holder. Can be individual or company.

bank_account.bank_name string
Name of the bank associated with the account number.

bank_account.country string
The country in which the bank account is located.

bank_account.currency string
Three-letter ISO currency code, in lowercase. Must be a supported currency.

bank_account.last4 string
The last four digits of the bank account number.

bank_account.routing_number string
The routing number, sort code, or other country-appropriate institution number for the bank account.

bank_account.swift_bic string
The SWIFT of the bank associated with the bank account.
metadata string
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
status string
The status of the external account. If a payout fails, the status is updated to errored and payouts will be stopped until the account details are updated. Can be new or errored.
type string
The type of external account. Can be bank_account.

Create an external account

POST /v1/external_accounts

curl https://api.yorlet.com/v1/external_accounts \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "ext_acct_test",
  "object": "external_account",
  "created": 1627210800,
  "available_payout_methods": [],
  "bank_account": {
    "account_holder_name": "Jane Doe",
    "account_holder_type": "individual",
    "bank_name": null,
    "country": "GB",
    "currency": "gbp",
    "last4": "1234",
    "routing_number": "101010",
    "swift_bic": null
  },
  "metadata": {},
  "status": "new",
  "type": "bank_account"
}

Create a new external account.

Parameters

bank_account required object
The bank account details.

bank_account.account_holder_name required
The name of the account holder.

bank_account.account_holder_type required
The type of account holder. Can be company or individual.

bank_account.account_number required
The bank account number.

bank_account.country required
The country in which the bank account is located.

bank_account.currency required
The currency the bank account is in.

bank_account.routing_number optional
The routing number, sort code, or other country-appropriate institution number for the bank account.

bank_account.swift_bic optional
The SWIFT of the bank associated with the bank account.
type required
The type of external account. Can be bank_account.
metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Returns

Returns the external account object if the request succeeded.

Retrieve an external account

GET /v1/external_accounts/:id

curl https://api.yorlet.com/v1/external_accounts/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "ext_acct_test",
  "object": "external_account",
  "created": 1627210800,
  "available_payout_methods": [],
  "bank_account": {
    "account_holder_name": "Jane Doe",
    "account_holder_type": "individual",
    "bank_name": null,
    "country": "GB",
    "currency": "gbp",
    "last4": "1234",
    "routing_number": "101010",
    "swift_bic": null
  },
  "metadata": {},
  "status": "new",
  "type": "bank_account"
}

Retrieve the details about a specific external account.

Parameters

No parameters

Returns

Returns the external account object.

Update an external account

POST /v1/external_accounts/:id

curl https://api.yorlet.com/v1/external_accounts/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "ext_acct_test",
  "object": "external_account",
  "created": 1627210800,
  "available_payout_methods": [],
  "bank_account": {
    "account_holder_name": "Jane Doe",
    "account_holder_type": "individual",
    "bank_name": null,
    "country": "GB",
    "currency": "gbp",
    "last4": "1234",
    "routing_number": "101010",
    "swift_bic": null
  },
  "metadata": {},
  "status": "new",
  "type": "bank_account"
}

Updates the metadata. Other bank account details are not editable by design.

Parameters

metadata optional object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Returns

Returns the updated external account object.

Delete an external account

DELETE /v1/external_accounts/:id

curl https://api.yorlet.com/v1/external_accounts/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "ext_acct_test",
  "object": "external_account",
  "deleted": true
}

Deletes the external account.

Parameters

No parameters

Returns

Returns the deleted external account object.

List all external accounts

GET /v1/external_accounts

curl https://api.yorlet.com/v1/external_accounts \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "ext_acct_test",
      "object": "external_account",
      "created": 1627210800,
      "available_payout_methods": [],
      "bank_account": {
        "account_holder_name": "Jane Doe",
        "account_holder_type": "individual",
        "bank_name": null,
        "country": "GB",
        "currency": "gbp",
        "last4": "1234",
        "routing_number": "101010",
        "swift_bic": null
      },
      "metadata": {},
      "status": "new",
      "type": "bank_account"
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of external accounts. The external accounts are returned sorted by creation date, with the most recently created external accounts appearing first.

Parameters

No parameters

Returns

A object with a data property that contains an array of external accounts.

Payment Methods

Endpoints

POST    /v1/payment_methods
POST    /v1/payment_methods/:id/fund_bank_transfer
GET     /v1/payment_methods

Payment method objects represent customer’s payment instruments. They can be used with Subscriptions, Invoices and Transactions to collect payments or be saved to Customer objects for future use.

The payment method object

The payment method object

{
  "id": "pm_test",
  "object": "payment_method",
  "created": 1627210800,
  "bank_transfer": {
    "balance": 0,
    "account_number": "00000000",
    "bank_name": "Barclays Bank UK PLC",
    "sort_code": "230000",
    "reconciliation_deadline": null
  },
  "billing_details": {
    "email": "[email protected]",
    "name": "Jane Doe"
  },
  "customer": null,
  "mandate": null,
  "receiver": null,
  "status": "pending",
  "type": "bank_transfer"
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be payment_method.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
alipay object
This object contains details about the Alipay method.
autogiro object
This object contains details about the Autogiro method.
bacs_debit object
This object contains details about the Bacs Direct Debit method.
bank_transfer string
This object contains details about the bank transfer method.
billing_details object
Billing information for the payment method.
card object
This object contains details about the Card method.
currency string
customer stringexpandable
ID of the customer associated with this payment method.
direct_transfer object
This object contains details about the direct transfer.
fronted object
This object contains details about the Fronted payment method.
gbp_credit_transfer object
This object contains details about the UK Bank Account.
mandate object
Information related to the mandate for the payment method.
receiver object
Information related to the amount received and charged from the payment method.
sepa_debit object
This object contains details about the SEPA Direct Debit method.
status string
The status of the payment method.
type string
The type of the payment method.

Create a payment method

POST /v1/payment_methods

curl https://api.yorlet.com/v1/payment_methods \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "pm_test",
  "object": "payment_method",
  "created": 1627210800,
  "bank_transfer": {
    "balance": 0,
    "account_number": "00000000",
    "bank_name": "Barclays Bank UK PLC",
    "sort_code": "230000",
    "reconciliation_deadline": null
  },
  "billing_details": {
    "email": "[email protected]",
    "name": "Jane Doe"
  },
  "customer": null,
  "mandate": null,
  "receiver": null,
  "status": "pending",
  "type": "bank_transfer"
}

You can only create alipay, bank_transfer, and fronted payment methods using this API. To remain compliant with scheme requirements, use the Payment Method Session API to create other payment methods.

Parameters

customer required
The ID of customer you wish to create a payment method for.
type required
The type of payment method to create. Can be alipay, bank_transfer, direct_transfer or pay_by_bank.
bank_transfer optional object
If this is a bank_transfer payment method, this object contains details about the Bank Transfer payment method.

bank_transfer.currency required
Can be eur or gbp.

bank_transfer.country optional
Can be GB or IE.

Returns

Returns a payment method object if successful.

Simulate a bank transfer

POST /v1/payment_methods/:id/fund_bank_transfer

curl https://api.yorlet.com/v1/payment_methods/:id/fund_bank_transfer \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "pm_test",
  "object": "payment_method",
  "created": 1627210800,
  "bank_transfer": {
    "balance": 0,
    "account_number": "00000000",
    "bank_name": "Barclays Bank UK PLC",
    "sort_code": "230000",
    "reconciliation_deadline": null
  },
  "billing_details": {
    "email": "[email protected]",
    "name": "Jane Doe"
  },
  "customer": null,
  "mandate": null,
  "receiver": null,
  "status": "pending",
  "type": "bank_transfer"
}

Simulates an external bank transfer and adds funds to a the payment method's balance. This method can only be called in test mode.

Parameters

amount required integer
reference required

Returns

Returns a payment method object if successful.

List all payment methods

GET /v1/payment_methods

curl https://api.yorlet.com/v1/payment_methods \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "pm_test",
      "object": "payment_method",
      "created": 1627210800,
      "bank_transfer": {
        "balance": 0,
        "account_number": "00000000",
        "bank_name": "Barclays Bank UK PLC",
        "sort_code": "230000",
        "reconciliation_deadline": null
      },
      "billing_details": {
        "email": "[email protected]",
        "name": "Jane Doe"
      },
      "customer": null,
      "mandate": null,
      "receiver": null,
      "status": "pending",
      "type": "bank_transfer"
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of payment methods.

Parameters

No parameters

Returns

A object with a data property that contains an array of payment methods.

Payment Method Sessions

Endpoints

POST    /v1/payment_method_sessions
GET     /v1/payment_method_sessions/:id

To create an payment method session, you create a payment method session object.

The payment method session object

The payment method session object

{
  "id": "pmsess_test",
  "object": "payment_method_session",
  "created": 1627210800,
  "customer": null,
  "metadata": {},
  "payment_method": null,
  "payment_method_types": [],
  "return_url": null,
  "subscription": null,
  "url": "https://pay.yorlet.com/payment_methods/pmsess_kfls092pPQalaj2"
}

Attributes

id string
Unique identifier for the object.
object string
String representing the object's type. Objects of the same type share the same value. Can be payment_method_session.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
customer stringexpandable
ID of the customer associated with this transaction.
metadata object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
payment_method string
The ID of the payment method created by this session.
payment_method_types array
The payment method types allowed to be used to create the transaction.
return_url string
The url to redirect the customer to after the payment completes.
status string
The transactions status of the payment session. Can be paid or unpaid.
subscription stringexpandable
The ID of the subscription to collect the payment method for.
url string
The URL to redirect the user to complete the payment method session.

Create a payment method session

POST /v1/payment_method_sessions

curl https://api.yorlet.com/v1/payment_method_sessions \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "pmsess_test",
  "object": "payment_method_session",
  "created": 1627210800,
  "customer": null,
  "metadata": {},
  "payment_method": null,
  "payment_method_types": [],
  "return_url": null,
  "subscription": null,
  "url": "https://pay.yorlet.com/payment_methods/pmsess_kfls092pPQalaj2"
}

Parameters

customer required
The ID of customer you wish to collect a payment method for.
payment_method_types required array
The type of payment method you wish to collect. Can be autogiro, bacs_debit, card or sepa_debit.
return_url optional
The URL to redirect the user to after the payment method is collected.
send_email optional boolean
Send the URL to the customer email address.
subscription optional
The ID of the subscription to collect the payment method for.

Returns

Returns the payment method session object if the request succeeded.

Retrieve a payment method session

GET /v1/payment_method_sessions/:id

curl https://api.yorlet.com/v1/payment_method_sessions/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "pmsess_test",
  "object": "payment_method_session",
  "created": 1627210800,
  "customer": null,
  "metadata": {},
  "payment_method": null,
  "payment_method_types": [],
  "return_url": null,
  "subscription": null,
  "url": "https://pay.yorlet.com/payment_methods/pmsess_kfls092pPQalaj2"
}

Parameters

No parameters

Returns

Returns a payment method session object if a valid identifier was provided.

Products Resources

Prices

Endpoints

POST    /v1/prices
GET     /v1/prices/:id
POST    /v1/prices/:id
DELETE  /v1/prices/:id
GET     /v1/prices

Prices are used to define the cost and currency of a product.

The price object

The price object

{
  "id": "product_id",
  "object": "price",
  "created": 1627210800,
  "description": null,
  "recurring": null
}

Attributes

id string
Unique identifier for the price
object string
String representing the object's type. Objects of the same type share the same value. Can be price.
active boolean
Whether the price is active or not.
amount integer
The amount to be charged, represented as a whole integer.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
currency string
The currency of the price.
description string
The description of the price.
name string
The name of the price.
product stringexpandable
The product the price belongs to.
recurring object
An object describing the recurring schedule of the price.

recurring.interval string
The frequency of the recurring schedule.

recurring.interval_count integer
The number of intervals between each charge.
type string
The type of the price.

Create a price

POST /v1/prices

curl https://api.yorlet.com/v1/prices \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "product_id",
  "object": "price",
  "created": 1627210800,
  "description": null,
  "recurring": null
}

Create a price. You can create a product to immediately associate with a price.

Parameters

amount required integer
currency required
type required
Can be one_time or recurring.
active optional boolean
description optional
product optional
product_data optional object

product_data.description required

product_data.name required

product_data.active optional boolean

product_data.statement_descriptor optional
recurring optional object

recurring.interval required

recurring.interval_count optional integer
tax_behavior optional
Can be exclusive, inclusive or unspecified.

Returns

Returns the price object if the request succeeded.

Retrieve a price

GET /v1/prices/:id

curl https://api.yorlet.com/v1/prices/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "product_id",
  "object": "price",
  "created": 1627210800,
  "description": null,
  "recurring": null
}

Parameters

No parameters

Returns

Returns a price object if a valid identifier was provided.

Update a price

POST /v1/prices/:id

curl https://api.yorlet.com/v1/prices/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "product_id",
  "object": "price",
  "created": 1627210800,
  "description": null,
  "recurring": null
}

Parameters

active optional boolean
description optional
tax_behavior optional
Can be exclusive, inclusive or unspecified.

Returns

Returns the price object if the request succeeded.

Delete a price

DELETE /v1/prices/:id

curl https://api.yorlet.com/v1/prices/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "product_id",
  "object": "price",
  "deleted": true
}

Parameters

No parameters

Returns

Returns the price object if the request succeeded.

List prices

GET /v1/prices

curl https://api.yorlet.com/v1/prices \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "product_id",
  "object": "price",
  "created": 1627210800,
  "description": null,
  "recurring": null
}

Parameters

No parameters

Returns

Returns a list of prices if the request succeeded.

Products

Endpoints

POST    /v1/products
GET     /v1/products/:id
POST    /v1/products/:id
DELETE  /v1/products/:id
GET     /v1/products

Products describe specific goods or services you offer to your customer. These can be attached to subscriptions and invoices.

The product object

The product object

{
  "id": "product_id",
  "object": "product",
  "accounting_code": null,
  "active": true,
  "created": 1627210800,
  "default_price": null,
  "description": "Product 1 description",
  "name": "Product 1",
  "statement_descriptor": "Product 1 statement descriptor"
}

Attributes

id string
Unique identifier for the product
object string
String representing the object's type. Objects of the same type share the same value. Can be product.
accounting_code string
The accounting code to use for the product.
active boolean
Whether the product is active or not.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
default_price stringexpandable
The default price for the product.
description string
The description of the product.
name string
The name of the product.
statement_descriptor string
The statement descriptor of the product.

Create a product

POST /v1/products

curl https://api.yorlet.com/v1/products \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "product_id",
  "object": "product",
  "accounting_code": null,
  "active": true,
  "created": 1627210800,
  "default_price": null,
  "description": "Product 1 description",
  "name": "Product 1",
  "statement_descriptor": "Product 1 statement descriptor"
}

Create a product. You can create products for subscriptions and invoices.

Parameters

name required
accounting_code optional
active optional boolean
default_price optional
default_price_data optional object

default_price_data.amount required number

default_price_data.currency required

default_price_data.description optional

default_price_data.recurring optional object

default_price_data.recurring.interval required
Can be month or week.

default_price_data.recurring.interval_count optional number

default_price_data.type optional
Can be one_time or recurring.
description optional
statement_descriptor optional

Returns

Returns the product object if the request succeeded.

Retrieve a product

GET /v1/products/:id

curl https://api.yorlet.com/v1/products/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "product_id",
  "object": "product",
  "accounting_code": null,
  "active": true,
  "created": 1627210800,
  "default_price": null,
  "description": "Product 1 description",
  "name": "Product 1",
  "statement_descriptor": "Product 1 statement descriptor"
}

Parameters

No parameters

Returns

Returns a product object if a valid identifier was provided.

Update a product

POST /v1/products/:id

curl https://api.yorlet.com/v1/products/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "product_id",
  "object": "product",
  "accounting_code": null,
  "active": true,
  "created": 1627210800,
  "default_price": null,
  "description": "Product 1 description",
  "name": "Product 1",
  "statement_descriptor": "Product 1 statement descriptor"
}

Parameters

accounting_code optional
active optional boolean
default_price optional
description optional
name optional
statement_descriptor optional

Returns

Returns the product object if the update succeeded.

Delete a product

DELETE /v1/products/:id

curl https://api.yorlet.com/v1/products/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "product_id",
  "object": "product",
  "deleted": true
}

Parameters

No parameters

Returns

If the subscription ID does not exist, this call throws an error.

List products

GET /v1/products

curl https://api.yorlet.com/v1/products \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "product_id",
      "object": "product",
      "accounting_code": null,
      "active": true,
      "created": 1627210800,
      "default_price": null,
      "description": "Product 1 description",
      "name": "Product 1",
      "statement_descriptor": "Product 1 statement descriptor"
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

Returns a list of products.

Tax Rates

Endpoints

POST    /v1/tax_rates
GET     /v1/tax_rates/:id
POST    /v1/tax_rates/:id
DELETE  /v1/tax_rates/:id
GET     /v1/tax_rates

Tax rates are used to calculate the tax amount for a given subscription or invoice.

The tax rate object

The tax rate object

{
  "id": "tax_rate_id",
  "object": "tax_rate",
  "active": true,
  "country": "US",
  "created": 1627210800,
  "description": "Tax rate description",
  "inclusive": true,
  "jurisdiction": "jurisdiction",
  "name": "Tax rate name",
  "percentage": 0.1,
  "state": "CA"
}

Attributes

id string
Unique identifier for the tax rate
object string
String representing the object's type. Objects of the same type share the same value. Can be tax_rate.
active boolean
Whether the tax rate is active or not.
country string
The country the tax rate applies to.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
description string
The description of the tax rate.
inclusive boolean
Whether the tax rate is inclusive or exclusive.
jurisdiction string
The jurisdiction for the tax rate.
name string
The name of the tax rate.
percentage number
The percentage of the tax rate.
state string
The state the tax rate applies to.

Create a tax rate

POST /v1/tax_rates

curl https://api.yorlet.com/v1/tax_rates \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "tax_rate_id",
  "object": "tax_rate",
  "active": true,
  "country": "US",
  "created": 1627210800,
  "description": "Tax rate description",
  "inclusive": true,
  "jurisdiction": "jurisdiction",
  "name": "Tax rate name",
  "percentage": 0.1,
  "state": "CA"
}

Create a tax rate. You can create tax rates for subscriptions and invoices.

Parameters

name required
percentage required number
active optional boolean
country optional
description optional
inclusive optional boolean
jurisdiction optional
state optional

Returns

Returns the tax rate object if the request succeeded.

Retrieve a tax rate

GET /v1/tax_rates/:id

curl https://api.yorlet.com/v1/tax_rates/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "tax_rate_id",
  "object": "tax_rate",
  "active": true,
  "country": "US",
  "created": 1627210800,
  "description": "Tax rate description",
  "inclusive": true,
  "jurisdiction": "jurisdiction",
  "name": "Tax rate name",
  "percentage": 0.1,
  "state": "CA"
}

Parameters

No parameters

Returns

Returns a tax rate object if a valid identifier was provided.

Update a tax rate

POST /v1/tax_rates/:id

curl https://api.yorlet.com/v1/tax_rates/:id \ 
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \

Example Response

{
  "id": "tax_rate_id",
  "object": "tax_rate",
  "active": true,
  "country": "US",
  "created": 1627210800,
  "description": "Tax rate description",
  "inclusive": true,
  "jurisdiction": "jurisdiction",
  "name": "Tax rate name",
  "percentage": 0.1,
  "state": "CA"
}

Parameters

active optional boolean
country optional
description optional
jurisdiction optional
name optional
state optional

Returns

Returns a tax rate object if a valid identifier was provided.

Delete a tax rate

DELETE /v1/tax_rates/:id

curl https://api.yorlet.com/v1/tax_rates/:id \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "tax_rate_id",
  "object": "tax_rate",
  "deleted": true
}

Parameters

No parameters

Returns

Returns the tax rate object if the request succeeded.

List tax rates

GET /v1/tax_rates

curl https://api.yorlet.com/v1/tax_rates \ 
-H "Authorization: Bearer {API_KEY}" \

Example Response

{
  "id": "tax_rate_id",
  "object": "tax_rate",
  "active": true,
  "country": "US",
  "created": 1627210800,
  "description": "Tax rate description",
  "inclusive": true,
  "jurisdiction": "jurisdiction",
  "name": "Tax rate name",
  "percentage": 0.1,
  "state": "CA"
}

Parameters

No parameters

Returns

Returns a list of tax rates if the request succeeded.

Billing Resources

Credit Notes

Endpoints

POST    /v1/credit_notes
POST    /v1/credit_notes/preview
GET     /v1/credit_notes/:id
POST    /v1/credit_notes/:id
GET     /v1/credit_notes/:id/lines
POST    /v1/credit_notes/:id/void
GET     /v1/credit_notes/

Issue a credit note to adjust an invoice's amount after the invoice is finalized.

The credit note object

The credit note object

{
  "id": "cn_lc9bfxsv9EsTVzzJ",
  "object": "credit_note",
  "created": 1627210800,
  "amount": 100000,
  "currency": "gbp",
  "customer": "cus_ku6643te7OcjFIGh",
  "description": null,
  "discount_amount": 0,
  "invoice": "inv_lc933wkpuBDjS0TO",
  "memo": "Credit note for duplicate charge",
  "metadata": {},
  "number": "NZ47LVB3-0001-CN-01",
  "out_of_band_amount": 0,
  "reason": "duplicate",
  "subtotal": 100000,
  "subtotal_excluding_tax": 100000,
  "status": "issued",
  "tax_amounts": [],