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": [],
  "total": 100000,
  "total_excluding_tax": 100000,
  "type": "pre_payment",
  "voided_at": 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 credit_note.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
amount integer
The credit note amount.
currency string
Three-letter ISO currency code, in lowercase.
customer stringexpandable
The ID of the customer.
description string
An arbitrary string attached to the object. Often useful for displaying to users.
discount_amount integer
The credit note discount amount.
invoice stringexpandable
The ID of the invoice.
memo string
The credit note’s memo appears on the credit note PDF.
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.
number string
A unique number that identifies this part payment.
out_of_band_amount integer
The credit note amount that was paid out of band.
reason string
Reason for issuing this credit note. Can be duplicate, fraudulent, order_change, product_unsatisfactory or other.
subtotal integer
The credit note subtotal.
subtotal_excluding_tax integer
The credit note subtotal excluding tax.
status string
The credit note status. Can be issued or voided.
tax_amounts array
The credit note tax amounts.
total integer
The credit note total.
total_excluding_tax integer
The credit note total excluding tax, but including discounts.
type string
The type of credit note. Can be pre_payment or post_payment.
voided_at timestamp
The date this credit note was voided. Measured in seconds since the Unix epoch.

The credit note line item object

The credit note object

{
  "id": "cnli_test",
  "object": "credit_note_line_item",
  "created": 1627210800,
  "amount": 100000,
  "amount_excluding_tax": 100000,
  "credit_note": "cn_test",
  "currency": "gbp",
  "description": null,
  "invoice_item": "ii_test",
  "tax_amounts": [],
  "type": "invoice_item"
}

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 credit_note_line_item.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
amount integer
The amount.
amount_excluding_tax integer
The amount excluding tax.
credit_note string
The ID of the credit note.
currency string
Three-letter ISO currency code, in lowercase.
description string
The credit note line item description.
invoice_item string
The ID of the invoice item.
tax_amounts array
The tax amounts.
type string
The part payment line item type. Can be invoice_item.

Create a credit note

POST /v1/credit_notes

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

Example Response

{
  "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": [],
  "total": 100000,
  "total_excluding_tax": 100000,
  "type": "pre_payment",
  "voided_at": null
}

Parameters

invoice required
ID of the invoice.
lines required array
A list of up to 10 line items to issue credit for.

lines.amount required integer
The amount of credit to apply to the line item.

lines.invoice_item required
The invoice item to credit.

lines.type required
Type of the credit note line item. Can be invoice_item.
memo optional
The credit note’s memo appears on the credit note PDF.
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.
out_of_band_amount optional integer
The amount credited outside of Yorlet.
reason optional
The reason for issuing the credit note. Can be duplicate, fraudulent, order_change, product_unsatisfactory or other.

Returns

Returns a credit note object if successful.

Preview a credit note

POST /v1/credit_notes/preview

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

Example Response

{
  "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": [],
  "total": 100000,
  "total_excluding_tax": 100000,
  "type": "pre_payment",
  "voided_at": null
}

Parameters

invoice required
ID of the invoice.
lines required array
A list of up to 10 line items to issue credit for.

lines.amount required integer
The amount of credit to apply to the line item.

lines.invoice_item required
The invoice item to credit.

lines.type required
Type of the credit note line item. Can be invoice_item.
memo optional
The credit note’s memo appears on the credit note PDF.
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.
out_of_band_amount optional integer
The amount credited outside of Yorlet.
reason optional
The reason for issuing the credit note. Can be duplicate, fraudulent, order_change, product_unsatisfactory or other.

Returns

Returns a credit note preview object if successful.

Retrieve a credit note

GET /v1/credit_notes/:id

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

Example Response

{
  "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": [],
  "total": 100000,
  "total_excluding_tax": 100000,
  "type": "pre_payment",
  "voided_at": null
}

Parameters

No parameters

Returns

Returns a credit note object if a valid identifier was provided.

Update a credit note

POST /v1/credit_notes/:id

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

Example Response

{
  "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": [],
  "total": 100000,
  "total_excluding_tax": 100000,
  "type": "pre_payment",
  "voided_at": null
}

Parameters

memo optional
The credit note’s memo appears on the credit note PDF.
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 an updated credit note object if a valid identifier was provided.

Retrieve a credit note's line items

GET /v1/credit_notes/:id/lines

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "cnli_test",
      "object": "credit_note_line_item",
      "created": 1627210800,
      "amount": 100000,
      "amount_excluding_tax": 100000,
      "credit_note": "cn_test",
      "currency": "gbp",
      "description": null,
      "invoice_item": "ii_test",
      "tax_amounts": [],
      "type": "invoice_item"
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

A object with a data property that contains an array of credit note line items.

Void a credit note

POST /v1/credit_notes/:id/void

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

Example Response

{
  "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": [],
  "total": 100000,
  "total_excluding_tax": 100000,
  "type": "pre_payment",
  "voided_at": null
}

Parameters

No parameters

Returns

Returns a voided credit note object if successful.

List all credit notes

GET /v1/credit_notes/

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

Example Response

{
  "object": "list",
  "data": [
    {
      "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": [],
      "total": 100000,
      "total_excluding_tax": 100000,
      "type": "pre_payment",
      "voided_at": null
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

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

Invoices

Endpoints

POST    /v1/invoices
GET     /v1/invoices/upcoming
GET     /v1/invoices/:id
POST    /v1/invoices/:id
DELETE  /v1/invoices/:id
POST    /v1/invoices/:id/finalize
POST    /v1/invoices/:id/pay
POST    /v1/invoices/:id/send
POST    /v1/invoices/:id/mark_uncollectible
POST    /v1/invoices/:id/void
GET     /v1/invoices

The invoice object

The invoice object

{
  "id": "inv_test",
  "object": "invoice",
  "created": 1627210800,
  "amount_due": 40000,
  "amount_paid": 0,
  "amount_remaining": 40000,
  "application": null,
  "applied_balance": 0,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "billing_reason": null,
  "collection_method": null,
  "currency": null,
  "custom_fields": null,
  "customer": null,
  "customer_address": null,
  "customer_email": null,
  "customer_name": null,
  "default_payment_method": null,
  "description": null,
  "discount": null,
  "discount_amount": 0,
  "due_date": null,
  "ending_balance": 0,
  "finalized_at": null,
  "footer": null,
  "from_invoice": {
    "action": null,
    "invoice": null
  },
  "hosted_invoice_url": null,
  "last_finalization_error": null,
  "late_payment_failure_invoice": null,
  "late_payment_failure": false,
  "lateset_revision": null,
  "marked_uncollectible_at": null,
  "metadata": {},
  "next_payment_attempt": null,
  "number_transfer_reference": null,
  "off_platform_reference": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "paid_at": null,
  "paid_off_platform": false,
  "paid": false,
  "part_payment_amount": 0,
  "payment_settings": {
    "payment_method_types": null
  },
  "pending_part_payment": false,
  "pending_transaction": false,
  "period_end": null,
  "period_start": null,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "source_dispute": null,
  "starting_balance": 0,
  "status": "open",
  "subscription": null,
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "total_tax_amounts": [],
  "transaction": null,
  "transfer_data": [],
  "voided_at": 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 invoice.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
amount_due integer
Final amount due at this time for this invoice.
amount_paid integer
The amount that was paid.
amount_remaining integer
The amount remaining that is due.
application stringexpandable
applied_balance integer
The customer balance applied to this invoice.
attempt_count integer
Number of payment attempts made for this invoice.
attempted boolean
Whether an attempt has been made to pay the invoice.
auto_advance boolean
billing_reason string
The reason why billing for this invoice was initiated.
collection_method string
When charging automatically, Yorlet will attempt to pay this invoice using the default source attached to the customer. When sending an invoice, Yorlet will email this invoice to the customer with payment instructions. Can be charge_automatically or send_invoice.
currency string
Three-letter ISO currency code, in lowercase.
custom_fields array
Custom fields displayed on the invoice.
customer stringexpandable
The ID of the customer who will be billed.
customer_address string
The address of the customer at the time the invoice was finalized.
customer_email string
The email of the customer at the time the invoice was finalized.
customer_name string
The name of the customer at the time the invoice was finalized.
default_payment_method stringexpandable
ID of the default payment method for the invoice. It must belong to the customer associated with the invoice.
description string
An arbitrary string attached to the object. Often useful for displaying to users.
discount object
Describes the current discount applied to this invoice, if there is one.
discount_amount integer
The amount that has been discounted for this invoice.
due_date timestamp
The date on which payment for this invoice is due. Measured in seconds since the Unix epoch.
ending_balance integer
Ending customer balance after the invoice is finalized.
finalized_at timestamp
The date this invoice was finalized. Measured in seconds since the Unix epoch.
footer string
Footer displayed on the invoice.
from_invoice object
Details of the invoice which was revised.
hosted_invoice_url string
The URL for the hosted invoice page, which allows customers to view and pay an invoice.
last_finalization_error string
The last finalization error on this invoice.
late_payment_failure_invoice string
The ID of the invoice generated by a late payment failure.
late_payment_failure boolean
Whether this invoice's payment failed after succeeding.
lateset_revision stringexpandable
The ID of the latest non-draft revision of this invoice.
marked_uncollectible_at timestamp
The date this invoice was marked as uncollectible. Measured in seconds since the Unix epoch.
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_payment_attempt timestamp
The date a payment will be attempted for this invoice. Measured in seconds since the Unix epoch.
number string
The invoice number.
number_transfer_reference string
The invoice number used for automatic reconciliation with manual bank transfers.
off_platform_reference string
The reference for a payment made off platform.
optimized_collection_date timestamp
The date this invoice was optimized. Measured in seconds since the Unix epoch.
optimized_collection_reason string
The reason why a optimized_collection_date was applied. Can be bacs_debit.
paid_at timestamp
The date this invoice was paid. Measured in seconds since the Unix epoch.
paid_off_platform boolean
Whether this invoice was paid off platform.
paid boolean
Whether this invoice has been paid.
part_payment_amount integer
The total part payment amount for this invoice.
payment_settings object
The payment settings for this invoice.
pending_part_payment boolean
Whether this invoice has a part payment that is currently unpaid.
pending_transaction boolean
Whether this invoice has a payment that is currently processing.
period_end timestamp
End of the billing period of this invoice. Measured in seconds since the Unix epoch.
period_start timestamp
Start of the billing period of this invoice. Measured in seconds since the Unix epoch.
post_payment_credit_notes_amount integer
Total amount of all post-payment credit notes issued for this invoice.
pre_payment_credit_notes_amount integer
Total amount of all pre-payment credit notes issued for this invoice.
source_dispute string
The dispute that created this invoice after a late payment failure.
starting_balance integer
Starting customer balance before the invoice is finalized.
status string
The status of the invoice. Can be draft, open, paid, uncollectible or void.
subscription string
The subscription that this invoice was prepared for, if any.
subtotal integer
The subtotal of this invoice.
tax integer
The amount of tax on this invoice.
total integer
Total after discounts and taxes.
total_tax_amounts array
The amount of tax applied to this invoice.
transaction stringexpandable
The ID of the transaction associated with this invoice.
transfer_data array
Array describing where funds from the payment will be transferred to for the invoice.
voided_at timestamp
The date this invoice was voided. Measured in seconds since the Unix epoch.

Create an invoice

POST /v1/invoices

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

Example Response

{
  "id": "inv_test",
  "object": "invoice",
  "created": 1627210800,
  "amount_due": 40000,
  "amount_paid": 0,
  "amount_remaining": 40000,
  "application": null,
  "applied_balance": 0,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "billing_reason": null,
  "collection_method": null,
  "currency": null,
  "custom_fields": null,
  "customer": null,
  "customer_address": null,
  "customer_email": null,
  "customer_name": null,
  "default_payment_method": null,
  "description": null,
  "discount": null,
  "discount_amount": 0,
  "due_date": null,
  "ending_balance": 0,
  "finalized_at": null,
  "footer": null,
  "from_invoice": {
    "action": null,
    "invoice": null
  },
  "hosted_invoice_url": null,
  "last_finalization_error": null,
  "late_payment_failure_invoice": null,
  "late_payment_failure": false,
  "lateset_revision": null,
  "marked_uncollectible_at": null,
  "metadata": {},
  "next_payment_attempt": null,
  "number_transfer_reference": null,
  "off_platform_reference": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "paid_at": null,
  "paid_off_platform": false,
  "paid": false,
  "part_payment_amount": 0,
  "payment_settings": {
    "payment_method_types": null
  },
  "pending_part_payment": false,
  "pending_transaction": false,
  "period_end": null,
  "period_start": null,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "source_dispute": null,
  "starting_balance": 0,
  "status": "open",
  "subscription": null,
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "total_tax_amounts": [],
  "transaction": null,
  "transfer_data": [],
  "voided_at": null
}

Parameters

application optional
The application ID this invoice is for.
apply_customer_balance optional boolean
Whether or not to apply the customers current balance when the invoice is finalized. Defaults to true.
collection_method optional
Can be charge_automatically or send_invoice.
coupon optional
The ID of the coupon to apply to the invoice. To clear the current discount, pass an empty string.
currency optional
Three-letter ISO currency code, in lowercase. Must be a supported currency. Can be eur, gbp, sek or usd.
custom_fields optional array

custom_fields.name required

custom_fields.value required
customer optional
The ID of the customer.
days_until_due optional integer
default_payment_method optional
description optional
An arbitrary string attached to the object. Often useful for displaying to users.
due_date optional
The date on which payment for this invoice is due.
from_invoice optional object

from_invoice.action required
Can be revision.

from_invoice.invoice required
payment_settings optional object
Payment settings for the transaction that is generated when the invoice is finalized.

payment_settings.payment_method_types optional array
period_end optional
The date this invoice period ends.
period_start optional
The date this invoice period starts.
send_finalization_email optional boolean
Whether or not to send an email to the customer when the invoice is finalized. Defaults to true.

Returns

Retrieve an upcoming invoice

GET /v1/invoices/upcoming

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

Example Response

{
  "id": "inv_test",
  "object": "invoice",
  "created": 1627210800,
  "amount_due": 40000,
  "amount_paid": 0,
  "amount_remaining": 40000,
  "application": null,
  "applied_balance": 0,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "billing_reason": null,
  "collection_method": null,
  "currency": null,
  "custom_fields": null,
  "customer": null,
  "customer_address": null,
  "customer_email": null,
  "customer_name": null,
  "default_payment_method": null,
  "description": null,
  "discount": null,
  "discount_amount": 0,
  "due_date": null,
  "ending_balance": 0,
  "finalized_at": null,
  "footer": null,
  "from_invoice": {
    "action": null,
    "invoice": null
  },
  "hosted_invoice_url": null,
  "last_finalization_error": null,
  "late_payment_failure_invoice": null,
  "late_payment_failure": false,
  "lateset_revision": null,
  "marked_uncollectible_at": null,
  "metadata": {},
  "next_payment_attempt": null,
  "number_transfer_reference": null,
  "off_platform_reference": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "paid_at": null,
  "paid_off_platform": false,
  "paid": false,
  "part_payment_amount": 0,
  "payment_settings": {
    "payment_method_types": null
  },
  "pending_part_payment": false,
  "pending_transaction": false,
  "period_end": null,
  "period_start": null,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "source_dispute": null,
  "starting_balance": 0,
  "status": "open",
  "subscription": null,
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "total_tax_amounts": [],
  "transaction": null,
  "transfer_data": [],
  "voided_at": null
}

Parameters

No parameters

Returns

Retrieve an invoice

GET /v1/invoices/:id

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

Example Response

{
  "id": "inv_test",
  "object": "invoice",
  "created": 1627210800,
  "amount_due": 40000,
  "amount_paid": 0,
  "amount_remaining": 40000,
  "application": null,
  "applied_balance": 0,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "billing_reason": null,
  "collection_method": null,
  "currency": null,
  "custom_fields": null,
  "customer": null,
  "customer_address": null,
  "customer_email": null,
  "customer_name": null,
  "default_payment_method": null,
  "description": null,
  "discount": null,
  "discount_amount": 0,
  "due_date": null,
  "ending_balance": 0,
  "finalized_at": null,
  "footer": null,
  "from_invoice": {
    "action": null,
    "invoice": null
  },
  "hosted_invoice_url": null,
  "last_finalization_error": null,
  "late_payment_failure_invoice": null,
  "late_payment_failure": false,
  "lateset_revision": null,
  "marked_uncollectible_at": null,
  "metadata": {},
  "next_payment_attempt": null,
  "number_transfer_reference": null,
  "off_platform_reference": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "paid_at": null,
  "paid_off_platform": false,
  "paid": false,
  "part_payment_amount": 0,
  "payment_settings": {
    "payment_method_types": null
  },
  "pending_part_payment": false,
  "pending_transaction": false,
  "period_end": null,
  "period_start": null,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "source_dispute": null,
  "starting_balance": 0,
  "status": "open",
  "subscription": null,
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "total_tax_amounts": [],
  "transaction": null,
  "transfer_data": [],
  "voided_at": null
}

Parameters

No parameters

Returns

Update an invoice

POST /v1/invoices/:id

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

Example Response

{
  "id": "inv_test",
  "object": "invoice",
  "created": 1627210800,
  "amount_due": 40000,
  "amount_paid": 0,
  "amount_remaining": 40000,
  "application": null,
  "applied_balance": 0,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "billing_reason": null,
  "collection_method": null,
  "currency": null,
  "custom_fields": null,
  "customer": null,
  "customer_address": null,
  "customer_email": null,
  "customer_name": null,
  "default_payment_method": null,
  "description": null,
  "discount": null,
  "discount_amount": 0,
  "due_date": null,
  "ending_balance": 0,
  "finalized_at": null,
  "footer": null,
  "from_invoice": {
    "action": null,
    "invoice": null
  },
  "hosted_invoice_url": null,
  "last_finalization_error": null,
  "late_payment_failure_invoice": null,
  "late_payment_failure": false,
  "lateset_revision": null,
  "marked_uncollectible_at": null,
  "metadata": {},
  "next_payment_attempt": null,
  "number_transfer_reference": null,
  "off_platform_reference": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "paid_at": null,
  "paid_off_platform": false,
  "paid": false,
  "part_payment_amount": 0,
  "payment_settings": {
    "payment_method_types": null
  },
  "pending_part_payment": false,
  "pending_transaction": false,
  "period_end": null,
  "period_start": null,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "source_dispute": null,
  "starting_balance": 0,
  "status": "open",
  "subscription": null,
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "total_tax_amounts": [],
  "transaction": null,
  "transfer_data": [],
  "voided_at": null
}

Parameters

collection_method optional
Can be charge_automatically or send_invoice.
coupon optional
The ID of the coupon to apply to the invoice. To clear the current discount, pass an empty string.
custom_fields optional array

custom_fields.name required

custom_fields.value required
days_until_due optional integer
default_payment_method optional
description optional
An arbitrary string attached to the object. Often useful for displaying to users.
due_date optional
The date on which payment for this invoice is due.
payment_settings optional object
Payment settings for the transaction that is generated when the invoice is finalized.

payment_settings.payment_method_types optional array

Returns

Delete an invoice

DELETE /v1/invoices/:id

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

Example Response

{
  "id": "inv_test",
  "object": "invoice",
  "deleted": true
}

Parameters

No parameters

Returns

Finalize an invoice

POST /v1/invoices/:id/finalize

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

Example Response

{
  "id": "inv_test",
  "object": "invoice",
  "created": 1627210800,
  "amount_due": 40000,
  "amount_paid": 0,
  "amount_remaining": 40000,
  "application": null,
  "applied_balance": 0,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "billing_reason": null,
  "collection_method": null,
  "currency": null,
  "custom_fields": null,
  "customer": null,
  "customer_address": null,
  "customer_email": null,
  "customer_name": null,
  "default_payment_method": null,
  "description": null,
  "discount": null,
  "discount_amount": 0,
  "due_date": null,
  "ending_balance": 0,
  "finalized_at": null,
  "footer": null,
  "from_invoice": {
    "action": null,
    "invoice": null
  },
  "hosted_invoice_url": null,
  "last_finalization_error": null,
  "late_payment_failure_invoice": null,
  "late_payment_failure": false,
  "lateset_revision": null,
  "marked_uncollectible_at": null,
  "metadata": {},
  "next_payment_attempt": null,
  "number_transfer_reference": null,
  "off_platform_reference": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "paid_at": null,
  "paid_off_platform": false,
  "paid": false,
  "part_payment_amount": 0,
  "payment_settings": {
    "payment_method_types": null
  },
  "pending_part_payment": false,
  "pending_transaction": false,
  "period_end": null,
  "period_start": null,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "source_dispute": null,
  "starting_balance": 0,
  "status": "open",
  "subscription": null,
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "total_tax_amounts": [],
  "transaction": null,
  "transfer_data": [],
  "voided_at": null
}

Parameters

send_finalization_email optional boolean
Whether or not to send an email to the customer when the invoice is finalized. Defaults to true.

Returns

Pay an invoice

POST /v1/invoices/:id/pay

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

Example Response

{
  "id": "inv_test",
  "object": "invoice",
  "created": 1627210800,
  "amount_due": 40000,
  "amount_paid": 0,
  "amount_remaining": 40000,
  "application": null,
  "applied_balance": 0,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "billing_reason": null,
  "collection_method": null,
  "currency": null,
  "custom_fields": null,
  "customer": null,
  "customer_address": null,
  "customer_email": null,
  "customer_name": null,
  "default_payment_method": null,
  "description": null,
  "discount": null,
  "discount_amount": 0,
  "due_date": null,
  "ending_balance": 0,
  "finalized_at": null,
  "footer": null,
  "from_invoice": {
    "action": null,
    "invoice": null
  },
  "hosted_invoice_url": null,
  "last_finalization_error": null,
  "late_payment_failure_invoice": null,
  "late_payment_failure": false,
  "lateset_revision": null,
  "marked_uncollectible_at": null,
  "metadata": {},
  "next_payment_attempt": null,
  "number_transfer_reference": null,
  "off_platform_reference": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "paid_at": null,
  "paid_off_platform": false,
  "paid": false,
  "part_payment_amount": 0,
  "payment_settings": {
    "payment_method_types": null
  },
  "pending_part_payment": false,
  "pending_transaction": false,
  "period_end": null,
  "period_start": null,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "source_dispute": null,
  "starting_balance": 0,
  "status": "open",
  "subscription": null,
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "total_tax_amounts": [],
  "transaction": null,
  "transfer_data": [],
  "voided_at": null
}

Parameters

internal_reference optional
An internal reference useful for tracking a payment made off-platform.
off_session optional boolean
paid_off_platform optional boolean
paid_off_platform_at optional
The date the payment was made off-platform.
payment_method optional
The ID of a payment method to be used. It must belong to the customer associated with the invoice being paid.

Returns

Send an invoice

POST /v1/invoices/:id/send

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

Example Response

{
  "id": "inv_test",
  "object": "invoice",
  "created": 1627210800,
  "amount_due": 40000,
  "amount_paid": 0,
  "amount_remaining": 40000,
  "application": null,
  "applied_balance": 0,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "billing_reason": null,
  "collection_method": null,
  "currency": null,
  "custom_fields": null,
  "customer": null,
  "customer_address": null,
  "customer_email": null,
  "customer_name": null,
  "default_payment_method": null,
  "description": null,
  "discount": null,
  "discount_amount": 0,
  "due_date": null,
  "ending_balance": 0,
  "finalized_at": null,
  "footer": null,
  "from_invoice": {
    "action": null,
    "invoice": null
  },
  "hosted_invoice_url": null,
  "last_finalization_error": null,
  "late_payment_failure_invoice": null,
  "late_payment_failure": false,
  "lateset_revision": null,
  "marked_uncollectible_at": null,
  "metadata": {},
  "next_payment_attempt": null,
  "number_transfer_reference": null,
  "off_platform_reference": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "paid_at": null,
  "paid_off_platform": false,
  "paid": false,
  "part_payment_amount": 0,
  "payment_settings": {
    "payment_method_types": null
  },
  "pending_part_payment": false,
  "pending_transaction": false,
  "period_end": null,
  "period_start": null,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "source_dispute": null,
  "starting_balance": 0,
  "status": "open",
  "subscription": null,
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "total_tax_amounts": [],
  "transaction": null,
  "transfer_data": [],
  "voided_at": null
}

Parameters

No parameters

Returns

Mark an invoice as uncollectible

POST /v1/invoices/:id/mark_uncollectible

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

Example Response

{
  "id": "inv_test",
  "object": "invoice",
  "created": 1627210800,
  "amount_due": 40000,
  "amount_paid": 0,
  "amount_remaining": 40000,
  "application": null,
  "applied_balance": 0,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "billing_reason": null,
  "collection_method": null,
  "currency": null,
  "custom_fields": null,
  "customer": null,
  "customer_address": null,
  "customer_email": null,
  "customer_name": null,
  "default_payment_method": null,
  "description": null,
  "discount": null,
  "discount_amount": 0,
  "due_date": null,
  "ending_balance": 0,
  "finalized_at": null,
  "footer": null,
  "from_invoice": {
    "action": null,
    "invoice": null
  },
  "hosted_invoice_url": null,
  "last_finalization_error": null,
  "late_payment_failure_invoice": null,
  "late_payment_failure": false,
  "lateset_revision": null,
  "marked_uncollectible_at": null,
  "metadata": {},
  "next_payment_attempt": null,
  "number_transfer_reference": null,
  "off_platform_reference": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "paid_at": null,
  "paid_off_platform": false,
  "paid": false,
  "part_payment_amount": 0,
  "payment_settings": {
    "payment_method_types": null
  },
  "pending_part_payment": false,
  "pending_transaction": false,
  "period_end": null,
  "period_start": null,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "source_dispute": null,
  "starting_balance": 0,
  "status": "open",
  "subscription": null,
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "total_tax_amounts": [],
  "transaction": null,
  "transfer_data": [],
  "voided_at": null
}

Parameters

No parameters

Returns

Void an invoice

POST /v1/invoices/:id/void

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

Example Response

{
  "id": "inv_test",
  "object": "invoice",
  "created": 1627210800,
  "amount_due": 40000,
  "amount_paid": 0,
  "amount_remaining": 40000,
  "application": null,
  "applied_balance": 0,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "billing_reason": null,
  "collection_method": null,
  "currency": null,
  "custom_fields": null,
  "customer": null,
  "customer_address": null,
  "customer_email": null,
  "customer_name": null,
  "default_payment_method": null,
  "description": null,
  "discount": null,
  "discount_amount": 0,
  "due_date": null,
  "ending_balance": 0,
  "finalized_at": null,
  "footer": null,
  "from_invoice": {
    "action": null,
    "invoice": null
  },
  "hosted_invoice_url": null,
  "last_finalization_error": null,
  "late_payment_failure_invoice": null,
  "late_payment_failure": false,
  "lateset_revision": null,
  "marked_uncollectible_at": null,
  "metadata": {},
  "next_payment_attempt": null,
  "number_transfer_reference": null,
  "off_platform_reference": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "paid_at": null,
  "paid_off_platform": false,
  "paid": false,
  "part_payment_amount": 0,
  "payment_settings": {
    "payment_method_types": null
  },
  "pending_part_payment": false,
  "pending_transaction": false,
  "period_end": null,
  "period_start": null,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "source_dispute": null,
  "starting_balance": 0,
  "status": "open",
  "subscription": null,
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "total_tax_amounts": [],
  "transaction": null,
  "transfer_data": [],
  "voided_at": null
}

Parameters

No parameters

Returns

List all invoices

GET /v1/invoices

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "inv_test",
      "object": "invoice",
      "created": 1627210800,
      "amount_due": 40000,
      "amount_paid": 0,
      "amount_remaining": 40000,
      "application": null,
      "applied_balance": 0,
      "attempt_count": 0,
      "attempted": false,
      "auto_advance": false,
      "billing_reason": null,
      "collection_method": null,
      "currency": null,
      "custom_fields": null,
      "customer": null,
      "customer_address": null,
      "customer_email": null,
      "customer_name": null,
      "default_payment_method": null,
      "description": null,
      "discount": null,
      "discount_amount": 0,
      "due_date": null,
      "ending_balance": 0,
      "finalized_at": null,
      "footer": null,
      "from_invoice": {
        "action": null,
        "invoice": null
      },
      "hosted_invoice_url": null,
      "last_finalization_error": null,
      "late_payment_failure_invoice": null,
      "late_payment_failure": false,
      "lateset_revision": null,
      "marked_uncollectible_at": null,
      "metadata": {},
      "next_payment_attempt": null,
      "number_transfer_reference": null,
      "off_platform_reference": null,
      "optimized_collection_date": null,
      "optimized_collection_reason": null,
      "paid_at": null,
      "paid_off_platform": false,
      "paid": false,
      "part_payment_amount": 0,
      "payment_settings": {
        "payment_method_types": null
      },
      "pending_part_payment": false,
      "pending_transaction": false,
      "period_end": null,
      "period_start": null,
      "post_payment_credit_notes_amount": 0,
      "pre_payment_credit_notes_amount": 0,
      "source_dispute": null,
      "starting_balance": 0,
      "status": "open",
      "subscription": null,
      "subtotal": 0,
      "tax": 0,
      "total": 0,
      "total_tax_amounts": [],
      "transaction": null,
      "transfer_data": [],
      "voided_at": null
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

List

Invoices Items

Endpoints

POST    /v1/invoice_items
GET     /v1/invoice_items/:id
POST    /v1/invoice_items/:id
DELETE  /v1/invoice_items/:id
GET     /v1/invoice_items

Bill customers for additional charges or rent.

The invoice item object

The invoice item object

{
  "id": "ii_test",
  "object": "invoice_item",
  "created": 1627210800,
  "accounting_code": null,
  "apply_after": null,
  "amount": 10000,
  "credit_amount": 0,
  "currency": "gbp",
  "customer": "cus_test",
  "description": null,
  "discount": 0,
  "invoice": "inv_test",
  "metadata": {},
  "part_payment_amount": 0,
  "price_data": {
    "amount": 10000,
    "currency": "gbp",
    "recurring": null,
    "tax_percent": 0,
    "type": "one_time"
  },
  "price": null,
  "proration_amount": 0,
  "subscription": null,
  "subscription_item": null,
  "tax": 0,
  "tax_percent": 0,
  "transfer_behavior": "automatic",
  "transfer_destination": null,
  "type": "rent",
  "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 invoice_item.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
accounting_code string
The accounting code to use for the invoice item.
apply_after timestamp
The date after which the invoice item will be applied.
amount integer
The integer amount in the smallest smallest currency unit of the amount to be applied to the invoice.
credit_amount integer
The credit amount applied to this invoice item.
currency string
Three-letter ISO currency code, in lowercase. Must be a supported currency.
customer stringexpandable
The ID of the customer who will be billed.
description string
An arbitrary string attached to the object. Often useful for displaying to users.
discount integer
The discount amount applied to this invoice item.
invoice stringexpandable
The ID of the associated invoice.
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.
part_payment_amount integer
The part payment amount applied to this invoice item.
price_data object
The price the customer is subscribed to.

price_data.amount integer
The amount to be charged, represented as a whole integer.

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

price_data.recurring object

price_data.recurring.interval string
The frequency at which a subscription is billed. One of day, week, month or year.

price_data.recurring.interval_count string
The number of intervals (specified in the interval attribute) between subscription billings. For example, interval=month and interval_count=3 bills every 3 months.

price_data.tax_percent integer
The tax percent to apply to the amount.

price_data.type string
One of one_time or recurring depending on whether the price is for a one-time purchase or a recurring (subscription) purchase. Invoice items created through the API will always be one_time.
price stringexpandable
The ID of the associated price.
proration_amount integer
The proration amount applied to this invoice item.
subscription stringexpandable
The ID of the associated subscription.
subscription_item stringexpandable
The ID of the associated subscription item that created this invoice item.
tax integer
The tax amount applied to this invoice item.
tax_percent integer
The tax percent used to calculate the tax amount.
transfer_behavior string
The transfer behavior for this invoice item. Can be automatic.
transfer_destination stringexpandable
ID of the owner that will receive the funds from this invoice item.
type string
The type of invoice item. Can be charge or rent.
unit stringexpandable
The ID of the associated unit.

Create an invoice item

POST /v1/invoice_items

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

Example Response

{
  "id": "ii_test",
  "object": "invoice_item",
  "created": 1627210800,
  "accounting_code": null,
  "apply_after": null,
  "amount": 10000,
  "credit_amount": 0,
  "currency": "gbp",
  "customer": "cus_test",
  "description": null,
  "discount": 0,
  "invoice": "inv_test",
  "metadata": {},
  "part_payment_amount": 0,
  "price_data": {
    "amount": 10000,
    "currency": "gbp",
    "recurring": null,
    "tax_percent": 0,
    "type": "one_time"
  },
  "price": null,
  "proration_amount": 0,
  "subscription": null,
  "subscription_item": null,
  "tax": 0,
  "tax_percent": 0,
  "transfer_behavior": "automatic",
  "transfer_destination": null,
  "type": "rent",
  "unit": null
}

Creates a new invoice item.

Parameters

amount required integer
The amount to be charged, represented as a whole integer if possible.
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 invoice item is for.
description required
The description for the invoice item, to be displayed to the customer.
type required
The type of the invoice item. Can be charge, rent or product.
apply_after optional
The date after which the invoice item will be applied.
invoice optional
The ID of the invoice the invoice item 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.
price optional
The ID of the price object.
tax_percent optional number
The tax percentage to use when calculating the tax amount.
transfer_behavior optional
The invoice item transfer behavior. The default is automatic. Can be automatic, owner or none.
transfer_destination optional
ID of the owner that will be the transfer destination. Only allowed when the invoice item transfer behavior is owner.
unit optional
The ID of the unit the invoice item is for.

Returns

Returns the invoice item object if the request succeeded.

Retrieve an invoice item

GET /v1/invoice_items/:id

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

Example Response

{
  "id": "ii_test",
  "object": "invoice_item",
  "created": 1627210800,
  "accounting_code": null,
  "apply_after": null,
  "amount": 10000,
  "credit_amount": 0,
  "currency": "gbp",
  "customer": "cus_test",
  "description": null,
  "discount": 0,
  "invoice": "inv_test",
  "metadata": {},
  "part_payment_amount": 0,
  "price_data": {
    "amount": 10000,
    "currency": "gbp",
    "recurring": null,
    "tax_percent": 0,
    "type": "one_time"
  },
  "price": null,
  "proration_amount": 0,
  "subscription": null,
  "subscription_item": null,
  "tax": 0,
  "tax_percent": 0,
  "transfer_behavior": "automatic",
  "transfer_destination": null,
  "type": "rent",
  "unit": null
}

Retrieves the invoice item with the given ID.

Parameters

No parameters

Returns

An invoice item object if a valid identifier was provided.

Update an invoice item

POST /v1/invoice_items/:id

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

Example Response

{
  "id": "ii_test",
  "object": "invoice_item",
  "created": 1627210800,
  "accounting_code": null,
  "apply_after": null,
  "amount": 10000,
  "credit_amount": 0,
  "currency": "gbp",
  "customer": "cus_test",
  "description": null,
  "discount": 0,
  "invoice": "inv_test",
  "metadata": {},
  "part_payment_amount": 0,
  "price_data": {
    "amount": 10000,
    "currency": "gbp",
    "recurring": null,
    "tax_percent": 0,
    "type": "one_time"
  },
  "price": null,
  "proration_amount": 0,
  "subscription": null,
  "subscription_item": null,
  "tax": 0,
  "tax_percent": 0,
  "transfer_behavior": "automatic",
  "transfer_destination": null,
  "type": "rent",
  "unit": null
}

Updates the invoice item with the given ID.

Parameters

amount optional integer
The amount to be charged, represented as a whole integer if possible.
description optional
The description for the invoice item, to be displayed to the customer.
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.
tax_percent optional number
The tax percentage to use when calculating the tax amount.
transfer_behavior optional
The invoice item transfer behavior. The default is automatic. Can be automatic, owner or none.
transfer_destination optional
ID of the owner that will be the transfer destination. Only allowed when the invoice item transfer behavior is owner.

Returns

The updated invoice item. Otherwise, this call throws an error.

Delete an invoice item

DELETE /v1/invoice_items/:id

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

Example Response

{
  "id": "ii_test",
  "object": "invoice_item",
  "deleted": true
}

Deletes the invoice item with the given ID.

Parameters

No parameters

Returns

An object with the deleted invoice item’s ID and a deleted flag upon success.

List all invoice items

GET /v1/invoice_items

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "ii_test",
      "object": "invoice_item",
      "created": 1627210800,
      "accounting_code": null,
      "apply_after": null,
      "amount": 10000,
      "credit_amount": 0,
      "currency": "gbp",
      "customer": "cus_test",
      "description": null,
      "discount": 0,
      "invoice": "inv_test",
      "metadata": {},
      "part_payment_amount": 0,
      "price_data": {
        "amount": 10000,
        "currency": "gbp",
        "recurring": null,
        "tax_percent": 0,
        "type": "one_time"
      },
      "price": null,
      "proration_amount": 0,
      "subscription": null,
      "subscription_item": null,
      "tax": 0,
      "tax_percent": 0,
      "transfer_behavior": "automatic",
      "transfer_destination": null,
      "type": "rent",
      "unit": null
    }
  ],
  "count": 1,
  "has_more": false
}

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

Parameters

No parameters

Returns

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

Part Payments

Endpoints

POST    /v1/part_payments
POST    /v1/part_payments/preview
GET     /v1/part_payments/:id
POST    /v1/part_payments/:id
GET     /v1/part_payments/:id/lines
POST    /v1/part_payments/:id/marked_paid
POST    /v1/part_payments/:id/void
GET     /v1/part_payments/

The part payment object

The part payment object

{
  "id": "pp_test",
  "object": "part_payment",
  "created": 1627210800,
  "amount": 100000,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "invoice": null,
  "metadata": {},
  "number": null,
  "out_of_band": false,
  "paid_at": null,
  "status": null,
  "transaction": 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 part_payment.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
amount integer
The deposit amount.
currency string
Three-letter ISO currency code, in lowercase.
customer stringexpandable
The ID of the customer.
description string
An arbitrary string attached to the object. Often useful for displaying to users.
invoice stringexpandable
The ID of the invoice.
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.
number string
A unique number that identifies this part payment
out_of_band boolean
Whether or not the part payment was paid outside of Yorlet.
paid_at timestamp
Time at which the part payment was paid. Measured in seconds since the Unix epoch.
status string
transaction stringexpandable
The ID of the transaction associated with this part payment.

The part payment line item object

The part payment object

{
  "id": "ppli_test",
  "object": "part_payment_line_item",
  "created": 1627210800,
  "amount": 100000,
  "currency": "gbp",
  "description": null,
  "invoice_item": "ii_test",
  "part_payment": "pp_test",
  "type": "invoice_line_item"
}

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 part_payment_line_item.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
amount integer
The deposit amount.
currency string
Three-letter ISO currency code, in lowercase.
description string
The line item description.
invoice_item string
The ID of the invoice item.
part_payment string
The ID of the part payment.
type string
The part payment line item type. Can be invoice_item.

Create a part payment

POST /v1/part_payments

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

Example Response

{
  "id": "pp_test",
  "object": "part_payment",
  "created": 1627210800,
  "amount": 100000,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "invoice": null,
  "metadata": {},
  "number": null,
  "out_of_band": false,
  "paid_at": null,
  "status": null,
  "transaction": null
}

Parameters

invoice required
ID of the invoice.
lines required array
A list of up to 10 line items to part pay.

lines.amount required integer
The part payment amount to apply to the line item.

lines.invoice_item required
The invoice item to part pay.
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.
out_of_band optional boolean

Returns

Returns a part payment object if successful.

Preview a part payment

POST /v1/part_payments/preview

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

Example Response

{
  "id": "pp_test",
  "object": "part_payment",
  "created": 1627210800,
  "amount": 100000,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "invoice": null,
  "metadata": {},
  "number": null,
  "out_of_band": false,
  "paid_at": null,
  "status": null,
  "transaction": null
}

Parameters

invoice required
ID of the invoice.
lines required array
A list of up to 10 line items to part pay.

lines.amount required integer
The part payment amount to apply to the line item.

lines.invoice_item required
The invoice item to part pay.
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.
out_of_band optional boolean

Returns

Returns a part payment preview object if successful.

Retrieve a part payment

GET /v1/part_payments/:id

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

Example Response

{
  "id": "pp_test",
  "object": "part_payment",
  "created": 1627210800,
  "amount": 100000,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "invoice": null,
  "metadata": {},
  "number": null,
  "out_of_band": false,
  "paid_at": null,
  "status": null,
  "transaction": null
}

Parameters

No parameters

Returns

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

Update a part payment

POST /v1/part_payments/:id

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

Example Response

{
  "id": "pp_test",
  "object": "part_payment",
  "created": 1627210800,
  "amount": 100000,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "invoice": null,
  "metadata": {},
  "number": null,
  "out_of_band": false,
  "paid_at": null,
  "status": null,
  "transaction": null
}

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.

Returns

Returns an updated part payment object if a valid identifier was provided.

Retrieve a part payment's line items

GET /v1/part_payments/:id/lines

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "ppli_test",
      "object": "part_payment_line_item",
      "created": 1627210800,
      "amount": 100000,
      "currency": "gbp",
      "description": null,
      "invoice_item": "ii_test",
      "part_payment": "pp_test",
      "type": "invoice_line_item"
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

A object with a data property that contains an array of part payment line items.

Mark a part payment as paid

POST /v1/part_payments/:id/marked_paid

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

Example Response

{
  "id": "pp_test",
  "object": "part_payment",
  "created": 1627210800,
  "amount": 100000,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "invoice": null,
  "metadata": {},
  "number": null,
  "out_of_band": false,
  "paid_at": null,
  "status": null,
  "transaction": null
}

Parameters

No parameters

Returns

Returns a voided part payment object if successful.

Void a part payment

POST /v1/part_payments/:id/void

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

Example Response

{
  "id": "pp_test",
  "object": "part_payment",
  "created": 1627210800,
  "amount": 100000,
  "currency": "gbp",
  "customer": null,
  "description": null,
  "invoice": null,
  "metadata": {},
  "number": null,
  "out_of_band": false,
  "paid_at": null,
  "status": null,
  "transaction": null
}

Parameters

No parameters

Returns

Returns a voided part payment object if successful.

List all part payments

GET /v1/part_payments/

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "pp_test",
      "object": "part_payment",
      "created": 1627210800,
      "amount": 100000,
      "currency": "gbp",
      "customer": null,
      "description": null,
      "invoice": null,
      "metadata": {},
      "number": null,
      "out_of_band": false,
      "paid_at": null,
      "status": null,
      "transaction": null
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

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

Subscriptions

Endpoints

POST    /v1/subscriptions
GET     /v1/subscriptions/:id
POST    /v1/subscriptions/:id
POST    /v1/subscriptions/:id/cancel
DELETE  /v1/subscriptions/:id/discount
POST    /v1/subscriptions/:id/progress
GET     /v1/subscriptions

The API allows you to create, cancel, and update your subscriptions. You can retrieve individual subscriptions as well as a list of all your subscriptions.

The subscription object

The subscription object

{
  "id": "sub_test",
  "object": "subscription",
  "created": 1627210800,
  "application": null,
  "billing_anchor": null,
  "cancel_at": null,
  "canceled_at": null,
  "current_period_end": null,
  "current_period_start": null,
  "current_phase": null,
  "custom_fields": null,
  "customer": null,
  "days_before_collection": null,
  "days_until_due": null,
  "default_payment_method": null,
  "discount": null,
  "end": null,
  "from_subscription": {
    "action": null,
    "subscription": null
  },
  "metadata": {},
  "next_period_end": null,
  "next_period_start": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "pause_collection": null,
  "phases": null,
  "start": 1723974546
}

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 subscription.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
application string
ID of the application associated with this subscription.
billing_anchor timestamp
Determines the date of the first full invoice. You can use this parameter to set a regular billing date for the subscription.
cancel_at timestamp
A date in the future at which the subscription will automatically be canceled. Measured in seconds since the Unix epoch.
canceled_at timestamp
The date the subscription was canceled. Measured in seconds since the Unix epoch.
collection_method string
Can be charge_automatically or send_invoice.
currency string
Three-letter ISO currency code, in lowercase. Must be a supported currency.
current_period_end timestamp
End of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.
current_period_start timestamp
Start of the current period that the subscription has been invoiced for.
current_phase object
custom_fields array
Custom fields displayed on each invoice this subscription creates.
customer stringexpandable
ID of the customer who owns the subscription.
days_before_collection integer
The number of days to create the invoice before the subscription's next period start date. Useful if you want to send the customer the upcoming invoice a few days before the subscription's next period start date. Only applies to subscriptions with collection_method=send_invoice.
days_until_due integer
default_payment_method stringexpandable
ID of the default payment method for the subscription. It must belong to the customer associated with the subscription.
description string
Subscriptions allow you to charge a customer on a recurring basis.
discount string
Describes the current discount applied to this subscription, if there is one. When billing, a discount applied to a subscription overrides a discount applied on a customer-wide basis.
end timestamp
Date when the subscription will end.
from_subscription object
Details of the subscription which was revised.
interval string
The frequency at which a subscription is billed. One of day, week, month or year.
interval_count string
The number of intervals (specified in the interval attribute) between subscription billings. For example, interval=month and interval_count=3 bills every 3 months.
latest_invoice string
The most recent invoice this subscription has generated.
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_period_end timestamp
The end date of the next billing cycle.
next_period_start timestamp
The start date of the next billing cycle.
optimized_collection_date timestamp
The date on which collection will be optimized.
optimized_collection_reason string
The reason collection was optimized.
pause_collection string
If specified, payment collection for this subscription will be paused.
phases array
The phases of the subscription schedule.
start timestamp
Date when the subscription will start.
status string
The status of the subscription.

Create a subscription

POST /v1/subscriptions

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

Example Response

{
  "id": "sub_test",
  "object": "subscription",
  "created": 1627210800,
  "application": null,
  "billing_anchor": null,
  "cancel_at": null,
  "canceled_at": null,
  "current_period_end": null,
  "current_period_start": null,
  "current_phase": null,
  "custom_fields": null,
  "customer": null,
  "days_before_collection": null,
  "days_until_due": null,
  "default_payment_method": null,
  "discount": null,
  "end": null,
  "from_subscription": {
    "action": null,
    "subscription": null
  },
  "metadata": {},
  "next_period_end": null,
  "next_period_start": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "pause_collection": null,
  "phases": null,
  "start": 1723974546
}

Parameters

customer required
The ID of the customer.
interval required
The interval of the subscription. Can be month, week or custom.
add_invoice_items optional array
A list of up to 10 invoice items that will be appended to the next invoice for this subscription.

add_invoice_items.description required
Description for the subscription item.

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

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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

add_invoice_items.price optional
The ID of the price object.

add_invoice_items.price_data optional object

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

add_invoice_items.price_data.currency required
Three-letter ISO currency code, in lowercase. Can be eur, gbp, sek or usd.

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

add_invoice_items.proration_behavior optional
Can be create_prorations or none.

add_invoice_items.tax_rate optional
The ID of the tax rate to apply to this item.

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

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.

add_invoice_items.unit optional
The ID of the unit. If type=rent you must provide a unit ID
application optional
The ID of the application to associate the subscription with.
billing_anchor optional
The date to anchor the subscription to.
collection_method optional
The collection method for the subscription. Can be charge_automatically or send_invoice.
coupon optional
The ID of the coupon to apply to the subscription.
currency optional
Three-letter ISO currency code, in lowercase. Must be a supported currency. Can be eur, gbp, sek or usd.
custom_fields optional array
Custom fields to add to the subscription.

custom_fields.name required
The name of the custom field.

custom_fields.value required
The value of the custom field.
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.
days_until_due optional integer
The number of days before the invoice is due.
default_payment_method optional
The ID of the payment method. It must belong to the customer associated with the subscription.
description optional
An arbitrary string attached to the object. Often useful for displaying to users.
end_date optional
The date this subscription should end. When a subscription ends the status will change to complete
from_subscription optional object

from_subscription.action required
Can be revision.

from_subscription.subscription required
interval_count optional integer
The interval count of the subscription.
items optional array
A list of up to 10 subscription items, each with attached price_data.

items.description required
Description for the subscription item.

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

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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

items.price optional
The ID of the price object.

items.price_data optional object

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

items.price_data.currency required
Three-letter ISO currency code, in lowercase. Can be eur, gbp, sek or usd.

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

items.proration_behavior optional
Can be create_prorations or none.

items.tax_rate optional
The ID of the tax rate to apply to this item.

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

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

items.unit optional
The ID of the unit. If type=rent you must provide a unit ID
payment_settings optional object
Payment settings to pass on to invoices created for this subscription.

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

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

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

phases.items.description required
Description for the subscription item.

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

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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

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

phases.items.price_data optional object

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

phases.items.price_data.currency required
Three-letter ISO currency code, in lowercase. Can be eur, gbp, sek or usd.

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

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

phases.items.tax_rate optional
The ID of the tax rate to apply to this item.

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

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.

phases.items.unit optional
The ID of the unit. If type=rent you must provide a unit ID
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
use_future_billing_date optional boolean
Use the future billing date for the subscription.

Returns

Returns the subscription object if the request succeeded.

Retrieve a subscription

GET /v1/subscriptions/:id

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

Example Response

{
  "id": "sub_test",
  "object": "subscription",
  "created": 1627210800,
  "application": null,
  "billing_anchor": null,
  "cancel_at": null,
  "canceled_at": null,
  "current_period_end": null,
  "current_period_start": null,
  "current_phase": null,
  "custom_fields": null,
  "customer": null,
  "days_before_collection": null,
  "days_until_due": null,
  "default_payment_method": null,
  "discount": null,
  "end": null,
  "from_subscription": {
    "action": null,
    "subscription": null
  },
  "metadata": {},
  "next_period_end": null,
  "next_period_start": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "pause_collection": null,
  "phases": null,
  "start": 1723974546
}

Parameters

No parameters

Returns

Returns a subscription object if a valid identifier was provided.

Update a subscription

POST /v1/subscriptions/:id

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

Example Response

{
  "id": "sub_test",
  "object": "subscription",
  "created": 1627210800,
  "application": null,
  "billing_anchor": null,
  "cancel_at": null,
  "canceled_at": null,
  "current_period_end": null,
  "current_period_start": null,
  "current_phase": null,
  "custom_fields": null,
  "customer": null,
  "days_before_collection": null,
  "days_until_due": null,
  "default_payment_method": null,
  "discount": null,
  "end": null,
  "from_subscription": {
    "action": null,
    "subscription": null
  },
  "metadata": {},
  "next_period_end": null,
  "next_period_start": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "pause_collection": null,
  "phases": null,
  "start": 1723974546
}

Parameters

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

add_invoice_items.description required
Description for the subscription item.

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

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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

add_invoice_items.price optional
The ID of the price object.

add_invoice_items.price_data optional object

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

add_invoice_items.price_data.currency required
Three-letter ISO currency code, in lowercase. Can be eur, gbp, sek or usd.

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

add_invoice_items.proration_behavior optional
Can be create_prorations or none.

add_invoice_items.tax_rate optional
The ID of the tax rate to apply to this item.

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

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.

add_invoice_items.unit optional
The ID of the unit. If type=rent you must provide a unit ID
billing_anchor optional
The date to anchor the subscription to.
billing_cycle_reset optional boolean
Reset the billing cycle from the billing anchor provided.
cancel_at optional
The time at which the subscription should be canceled. If set, the subscription will be scheduled for cancellation and will be canceled on the date provided.
collection_method optional
The collection method for the subscription. Can be charge_automatically or send_invoice.
coupon optional
The ID of the coupon to apply to the subscription.
custom_fields optional array
Custom fields to add to the subscription.

custom_fields.name required
The name of the custom field.

custom_fields.value required
The value of the custom field.
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.
days_until_due optional integer
The number of days before the invoice is due.
default_payment_method optional
The ID of the payment method. It must belong to the customer associated with the subscription.
description optional
An arbitrary string attached to the object. Often useful for displaying to users.
end_date optional
The date this subscription should end. When a subscription ends the status will change to complete
pause_collection optional object

pause_collection.behavior required

pause_collection.resumes_at optional
payment_settings optional object
Payment settings to pass on to invoices created for this subscription.

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

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

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

phases.items.description required
Description for the subscription item.

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

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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

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

phases.items.price_data optional object

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

phases.items.price_data.currency required
Three-letter ISO currency code, in lowercase. Can be eur, gbp, sek or usd.

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

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

phases.items.tax_rate optional
The ID of the tax rate to apply to this item.

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

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.

phases.items.unit optional
The ID of the unit. If type=rent you must provide a unit ID
proration_behavior optional
The proration behavior of the subscription when the billing anchor is updated. Can be create_prorations or none.

Returns

Returns the subscription object if the update succeeded.

Cancel a subscription

POST /v1/subscriptions/:id/cancel

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

Example Response

{
  "id": "sub_test",
  "object": "subscription",
  "created": 1627210800,
  "application": null,
  "billing_anchor": null,
  "cancel_at": null,
  "canceled_at": null,
  "current_period_end": null,
  "current_period_start": null,
  "current_phase": null,
  "custom_fields": null,
  "customer": null,
  "days_before_collection": null,
  "days_until_due": null,
  "default_payment_method": null,
  "discount": null,
  "end": null,
  "from_subscription": {
    "action": null,
    "subscription": null
  },
  "metadata": {},
  "next_period_end": null,
  "next_period_start": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "pause_collection": null,
  "phases": null,
  "start": 1723974546
}

Parameters

Returns

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

Delete a discount

DELETE /v1/subscriptions/:id/discount

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

Example Response

{
  "id": "sub_test",
  "object": "subscription",
  "created": 1627210800,
  "application": null,
  "billing_anchor": null,
  "cancel_at": null,
  "canceled_at": null,
  "current_period_end": null,
  "current_period_start": null,
  "current_phase": null,
  "custom_fields": null,
  "customer": null,
  "days_before_collection": null,
  "days_until_due": null,
  "default_payment_method": null,
  "discount": null,
  "end": null,
  "from_subscription": {
    "action": null,
    "subscription": null
  },
  "metadata": {},
  "next_period_end": null,
  "next_period_start": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "pause_collection": null,
  "phases": null,
  "start": 1723974546
}

Parameters

No parameters

Returns

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

Progress a subscription

POST /v1/subscriptions/:id/progress

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

Example Response

{
  "id": "sub_test",
  "object": "subscription",
  "created": 1627210800,
  "application": null,
  "billing_anchor": null,
  "cancel_at": null,
  "canceled_at": null,
  "current_period_end": null,
  "current_period_start": null,
  "current_phase": null,
  "custom_fields": null,
  "customer": null,
  "days_before_collection": null,
  "days_until_due": null,
  "default_payment_method": null,
  "discount": null,
  "end": null,
  "from_subscription": {
    "action": null,
    "subscription": null
  },
  "metadata": {},
  "next_period_end": null,
  "next_period_start": null,
  "optimized_collection_date": null,
  "optimized_collection_reason": null,
  "pause_collection": null,
  "phases": null,
  "start": 1723974546
}

You can manually progress a subscription to the next period.

Parameters

No parameters

Returns

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

List all subscriptions

GET /v1/subscriptions

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "sub_test",
      "object": "subscription",
      "created": 1627210800,
      "application": null,
      "billing_anchor": null,
      "cancel_at": null,
      "canceled_at": null,
      "current_period_end": null,
      "current_period_start": null,
      "current_phase": null,
      "custom_fields": null,
      "customer": null,
      "days_before_collection": null,
      "days_until_due": null,
      "default_payment_method": null,
      "discount": null,
      "end": null,
      "from_subscription": {
        "action": null,
        "subscription": null
      },
      "metadata": {},
      "next_period_end": null,
      "next_period_start": null,
      "optimized_collection_date": null,
      "optimized_collection_reason": null,
      "pause_collection": null,
      "phases": null,
      "start": 1723974546
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

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

Subscription Items

Endpoints

POST    /v1/subscription_items
GET     /v1/subscription_items/:id
POST    /v1/subscription_items/:id
DELETE  /v1/subscription_items/:id
GET     /v1/subscription_items

The API allows you to delete and update a subscription item. You can retrieve individual subscription items as well as a list of all your subscription items.

The subscription item object

The subscription item object

{
  "id": "si_test",
  "object": "subscription_item",
  "created": 1627210800,
  "description": null,
  "metadata": {},
  "price_data": {
    "amount": null,
    "currency": null,
    "recurring": null,
    "tax_percent": 0,
    "type": null
  },
  "price": null,
  "proration_behavior": "create_prorations",
  "subscription": null,
  "transfer_behavior": "automatic",
  "transfer_destination": 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 subscription_item.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
description string
Description for the subscription item.
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.
price_data object
The price the customer is subscribed to.

price_data.amount integer
The amount to be charged, represented as a whole integer.

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

price_data.recurring object

price_data.recurring.interval string
The frequency at which a subscription is billed. One of day, week, month or year.

price_data.recurring.interval_count string
The number of intervals (specified in the interval attribute) between subscription billings. For example, interval=month and interval_count=3 bills every 3 months.

price_data.tax_percent integer

price_data.type string
One of one_time or recurring depending on whether the price is for a one-time purchase or a recurring (subscription) purchase.
price stringexpandable
The ID of the associated price.
proration_behavior string
Determines how to handle prorations when there is a partial billing cycle. Can be create_prorations or none.
subscription string
The subscription this subscription_item belongs to.
transfer_behavior string
transfer_destination undefinedexpandable
ID of the owner that will receive the funds from this subscription item.
type string
Type of subscription item. Can be either rent or charge
unit string
Id of the unit that the subscription item is applied to.

Create a subscription item

POST /v1/subscription_items

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

Example Response

{
  "id": "si_test",
  "object": "subscription_item",
  "created": 1627210800,
  "description": null,
  "metadata": {},
  "price_data": {
    "amount": null,
    "currency": null,
    "recurring": null,
    "tax_percent": 0,
    "type": null
  },
  "price": null,
  "proration_behavior": "create_prorations",
  "subscription": null,
  "transfer_behavior": "automatic",
  "transfer_destination": null,
  "unit": null
}

Parameters

No parameters

Returns

Returns the newly created subscription item.

Retrieve a subscription item

GET /v1/subscription_items/:id

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

Example Response

{
  "id": "si_test",
  "object": "subscription_item",
  "created": 1627210800,
  "description": null,
  "metadata": {},
  "price_data": {
    "amount": null,
    "currency": null,
    "recurring": null,
    "tax_percent": 0,
    "type": null
  },
  "price": null,
  "proration_behavior": "create_prorations",
  "subscription": null,
  "transfer_behavior": "automatic",
  "transfer_destination": null,
  "unit": null
}

Parameters

No parameters

Returns

Returns a subscription item object if a valid identifier was provided.

Update a subscription item

POST /v1/subscription_items/:id

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

Example Response

{
  "id": "si_test",
  "object": "subscription_item",
  "created": 1627210800,
  "description": null,
  "metadata": {},
  "price_data": {
    "amount": null,
    "currency": null,
    "recurring": null,
    "tax_percent": 0,
    "type": null
  },
  "price": null,
  "proration_behavior": "create_prorations",
  "subscription": null,
  "transfer_behavior": "automatic",
  "transfer_destination": null,
  "unit": null
}

Parameters

No parameters

Returns

Returns the subscription item object if the update succeeded.

Delete a subscription item

DELETE /v1/subscription_items/:id

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

Example Response

{
  "id": "si_test",
  "object": "subscription_item",
  "deleted": true
}

Parameters

No parameters

Returns

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

List all subscription items

GET /v1/subscription_items

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "si_test",
      "object": "subscription_item",
      "created": 1627210800,
      "description": null,
      "metadata": {},
      "price_data": {
        "amount": null,
        "currency": null,
        "recurring": null,
        "tax_percent": 0,
        "type": null
      },
      "price": null,
      "proration_behavior": "create_prorations",
      "subscription": null,
      "transfer_behavior": "automatic",
      "transfer_destination": null,
      "unit": null
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

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

Owners Resources

Account Collections

Endpoints

POST    /v1/account_collections
GET     /v1/account_collections/:id
POST    /v1/account_collections/:id
POST    /v1/account_collections/:id/approve
POST    /v1/account_collections/:id/cancel
GET     /v1/account_collections

The account collection object

The account collection object

{
  "id": "ac_test",
  "object": "account_collection",
  "created": 1627210800,
  "amount": 40000,
  "currency": "gbp",
  "description": "Maintenance issue",
  "destination": "owner_to",
  "destination_owner_payment": null,
  "destination_platform_fee": 0,
  "destination_platform_fee_owner_payment": null,
  "documents": {
    "invoice_file": null
  },
  "refunded": false,
  "number": null,
  "owner_balance_transaction": null,
  "owner_payment": null,
  "owner": "owner_from",
  "period": {
    "end": null,
    "start": null
  },
  "references": {
    "invoice_number": null,
    "po_number": null
  },
  "status": "pending",
  "tax": 0,
  "tax_behavior": "exclusive",
  "tax_percent": 0,
  "tax_refunded": 0,
  "total": 0,
  "unit": "unit_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 account_collection.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
amount integer
The collection amount. This amount is in your currency and in the smallest currency unit.
amount_refunded integer
The amount refunded.
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.
destination stringexpandable
The ID of an owner account to allocate the collection funds to.
destination_owner_payment stringexpandable
If the destination is an owner account, this will be the ID of the payment that the destination account received for the collection.
destination_platform_fee integer
The destination platform fee percentage.
destination_platform_fee_owner_payment stringexpandable
If the destination platform fee was set, this will be the ID of the payment that the platform account received for the collection.
documents object
A hash of the documents associated with this account collection.

documents.invoice_file string
The invoice file associated with this account collection.
expense object
A hash of the expense details.
fee object
A hash of the fee details.
refunded string
Boolean value to indicate whether funds has been refunded or not.
number string
The number of the account collection.
owner_balance_transaction stringexpandable
ID of the owner balance transaction associated with this account collection.
owner_payment stringexpandable
ID of the owner payment associated with this account collection.
owner stringexpandable
The ID of the owner account to deduct the collection funds from.
period object
The period associated with this account collection.

period.end integer
End of the period, which must be greater than or equal to the start.

period.start integer
Start of the period.
references object
A hash of references for the account collection.

references.invoice_number string
The invoice number of the account collection.

references.po_number string
The purchase order number of the account collection.
status string
The status of the account collection. Can be canceled, paid or pending.
tax integer
The tax collected for this account collection.
tax_behavior string
The tax behavior for this account collection.
tax_percent float
The tax percent rate to use for this account collection.
tax_refunded integer
The tax refunded for this account collection.
total integer
The total for this account collection.
type undefined
The account collection type. Can be expense, fee or service_charge.
unit stringexpandable
ID of the unit associated with this account collection.

Create an account collection

POST /v1/account_collections

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

Example Response

{
  "id": "ac_test",
  "object": "account_collection",
  "created": 1627210800,
  "amount": 40000,
  "currency": "gbp",
  "description": "Maintenance issue",
  "destination": "owner_to",
  "destination_owner_payment": null,
  "destination_platform_fee": 0,
  "destination_platform_fee_owner_payment": null,
  "documents": {
    "invoice_file": null
  },
  "refunded": false,
  "number": null,
  "owner_balance_transaction": null,
  "owner_payment": null,
  "owner": "owner_from",
  "period": {
    "end": null,
    "start": null
  },
  "references": {
    "invoice_number": null,
    "po_number": null
  },
  "status": "pending",
  "tax": 0,
  "tax_behavior": "exclusive",
  "tax_percent": 0,
  "tax_refunded": 0,
  "total": 0,
  "unit": "unit_test"
}

Creates a new account collection.

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.
description required
An arbitrary string attached to the object. Often useful for displaying to users.
owner required
The ID of the owner the collection is for.
type required
The type of the account collection. Can be expense, fee or service_charge.
auto_advance optional boolean
Set auto_advance=true to attempt the account collection immediately regardless of whether the owner has the available funds. When setting auto_advance=false the account collection will be pending until it is approved. Only allowed when the account collection is not attached to an owner payout.
available_on optional
The date the account collection is available on.
destination optional
The ID of an owner account to allocate the collection funds to.
destination_platform_fee optional integer
The fee percent to charge the destination account. Only allowed when the destination is not the platform account.
documents optional object

documents.invoice_file optional
expense optional object

expense.code optional
Can be compliance, maintenance, utilities or other.
fee optional object

fee.code optional
Can be management_fee, tenant_find_fee or renewal_fee.
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.
owner_payout optional
The ID of the owner payout to attach the account collection to. The owner payout must be in the same currency as the account collection and have the status draft.
period optional object
A hash of the period this account collection relates to.

period.end optional
The period end date. Measured in seconds since the Unix epoch.

period.start optional
The period start date. Measured in seconds since the Unix epoch.
references optional object
A hash of references for the account collection.

references.invoice_number optional
The invoice number of the account collection.

references.po_number optional
The purchase order number of the account collection.
tax_behavior optional
The tax behavior to use for this account collection. Can be exclusive or inclusive.
tax_percent optional integer
The tax percent to use for this account collection.
unit optional
The ID of the unit this account collection is for.

Returns

Returns the account collection object if the request succeeded.

Retrieve an account collection

GET /v1/account_collections/:id

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

Example Response

{
  "id": "ac_test",
  "object": "account_collection",
  "created": 1627210800,
  "amount": 40000,
  "currency": "gbp",
  "description": "Maintenance issue",
  "destination": "owner_to",
  "destination_owner_payment": null,
  "destination_platform_fee": 0,
  "destination_platform_fee_owner_payment": null,
  "documents": {
    "invoice_file": null
  },
  "refunded": false,
  "number": null,
  "owner_balance_transaction": null,
  "owner_payment": null,
  "owner": "owner_from",
  "period": {
    "end": null,
    "start": null
  },
  "references": {
    "invoice_number": null,
    "po_number": null
  },
  "status": "pending",
  "tax": 0,
  "tax_behavior": "exclusive",
  "tax_percent": 0,
  "tax_refunded": 0,
  "total": 0,
  "unit": "unit_test"
}

Retrieves the account collection with the given ID.

Parameters

No parameters

Returns

Returns an account collection object if a valid identifier was provided.

Update an account collection

POST /v1/account_collections/:id

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

Example Response

{
  "id": "ac_test",
  "object": "account_collection",
  "created": 1627210800,
  "amount": 40000,
  "currency": "gbp",
  "description": "Maintenance issue",
  "destination": "owner_to",
  "destination_owner_payment": null,
  "destination_platform_fee": 0,
  "destination_platform_fee_owner_payment": null,
  "documents": {
    "invoice_file": null
  },
  "refunded": false,
  "number": null,
  "owner_balance_transaction": null,
  "owner_payment": null,
  "owner": "owner_from",
  "period": {
    "end": null,
    "start": null
  },
  "references": {
    "invoice_number": null,
    "po_number": null
  },
  "status": "pending",
  "tax": 0,
  "tax_behavior": "exclusive",
  "tax_percent": 0,
  "tax_refunded": 0,
  "total": 0,
  "unit": "unit_test"
}

Updates an account collection.

Parameters

description optional
An arbitrary string attached to the object. Often useful for displaying to users.
destination optional
The ID of an owner account to allocate the collection funds to.
destination_platform_fee optional integer
The fee percent to charge the destination account. Only allowed when the destination is not the platform 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.
period optional object
A hash of the period this account collection relates to.

period.end optional
The period end date. Measured in seconds since the Unix epoch.

period.start optional
The period start date. Measured in seconds since the Unix epoch.
unit optional
The ID of the unit this account collection is for.

Returns

Returns an updated account collection object if a valid identifier was provided.

Approve an account collection

POST /v1/account_collections/:id/approve

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

Example Response

{
  "id": "ac_test",
  "object": "account_collection",
  "created": 1627210800,
  "amount": 40000,
  "currency": "gbp",
  "description": "Maintenance issue",
  "destination": "owner_to",
  "destination_owner_payment": null,
  "destination_platform_fee": 0,
  "destination_platform_fee_owner_payment": null,
  "documents": {
    "invoice_file": null
  },
  "refunded": false,
  "number": null,
  "owner_balance_transaction": null,
  "owner_payment": null,
  "owner": "owner_from",
  "period": {
    "end": null,
    "start": null
  },
  "references": {
    "invoice_number": null,
    "po_number": null
  },
  "status": "pending",
  "tax": 0,
  "tax_behavior": "exclusive",
  "tax_percent": 0,
  "tax_refunded": 0,
  "total": 0,
  "unit": "unit_test"
}

Approves a pending account collection.

Parameters

Returns

Returns an account collection object if a valid identifier was provided.

Cancel an account collection

POST /v1/account_collections/:id/cancel

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

Example Response

{
  "id": "ac_test",
  "object": "account_collection",
  "created": 1627210800,
  "amount": 40000,
  "currency": "gbp",
  "description": "Maintenance issue",
  "destination": "owner_to",
  "destination_owner_payment": null,
  "destination_platform_fee": 0,
  "destination_platform_fee_owner_payment": null,
  "documents": {
    "invoice_file": null
  },
  "refunded": false,
  "number": null,
  "owner_balance_transaction": null,
  "owner_payment": null,
  "owner": "owner_from",
  "period": {
    "end": null,
    "start": null
  },
  "references": {
    "invoice_number": null,
    "po_number": null
  },
  "status": "pending",
  "tax": 0,
  "tax_behavior": "exclusive",
  "tax_percent": 0,
  "tax_refunded": 0,
  "total": 0,
  "unit": "unit_test"
}

Cancels a pending account collection.

Parameters

Returns

Returns an account collection object if a valid identifier was provided.

List all account collections

GET /v1/account_collections

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "ac_test",
      "object": "account_collection",
      "created": 1627210800,
      "amount": 40000,
      "currency": "gbp",
      "description": "Maintenance issue",
      "destination": "owner_to",
      "destination_owner_payment": null,
      "destination_platform_fee": 0,
      "destination_platform_fee_owner_payment": null,
      "documents": {
        "invoice_file": null
      },
      "refunded": false,
      "number": null,
      "owner_balance_transaction": null,
      "owner_payment": null,
      "owner": "owner_from",
      "period": {
        "end": null,
        "start": null
      },
      "references": {
        "invoice_number": null,
        "po_number": null
      },
      "status": "pending",
      "tax": 0,
      "tax_behavior": "exclusive",
      "tax_percent": 0,
      "tax_refunded": 0,
      "total": 0,
      "unit": "unit_test"
    }
  ],
  "count": 1,
  "has_more": false
}

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

Parameters

No parameters

Returns

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

Account Collection Refunds

Endpoints

POST    /v1/account_collections/:id/refunds
GET     /v1/account_collections/:id/refunds/:id
GET     /v1/account_collections/:id/refunds

The account collection refund object

The account collection refund object

{
  "id": "acr_test",
  "object": "account_collection",
  "created": 1627210800,
  "account_collection": null,
  "amount": 40000,
  "currency": "gbp",
  "description": null,
  "destination_owner_payment_refund": null,
  "owner_balance_transaction": null,
  "owner": null,
  "tax": 0,
  "tax_behavior": "exclusive",
  "tax_percent": 0,
  "total": 0,
  "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 account_collection.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
account_collection stringexpandable
amount integer
currency string
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html).
description string
An arbitrary string attached to the object. Often useful for displaying to users.
destination_owner_payment_refund stringexpandable
Linked owner payment refund for the account collection refund.
owner_balance_transaction stringexpandable
owner stringexpandable
tax integer
.
tax_behavior string
The tax behavior for this account collection.
tax_percent float
The tax percent rate to use for this account collection.
total integer
The total for this account collection refund.
type undefined
The transaction type. Can be or .
unit stringexpandable

Create an account collection refund

POST /v1/account_collections/:id/refunds

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

Example Response

{
  "id": "acr_test",
  "object": "account_collection",
  "created": 1627210800,
  "account_collection": null,
  "amount": 40000,
  "currency": "gbp",
  "description": null,
  "destination_owner_payment_refund": null,
  "owner_balance_transaction": null,
  "owner": null,
  "tax": 0,
  "tax_behavior": "exclusive",
  "tax_percent": 0,
  "total": 0,
  "unit": null
}

Parameters

amount optional integer
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.

Returns

Retrieve an account collection refund

GET /v1/account_collections/:id/refunds/:id

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

Example Response

{
  "id": "acr_test",
  "object": "account_collection",
  "created": 1627210800,
  "account_collection": null,
  "amount": 40000,
  "currency": "gbp",
  "description": null,
  "destination_owner_payment_refund": null,
  "owner_balance_transaction": null,
  "owner": null,
  "tax": 0,
  "tax_behavior": "exclusive",
  "tax_percent": 0,
  "total": 0,
  "unit": null
}

Parameters

No parameters

Returns

List all account collection refunds

GET /v1/account_collections/:id/refunds

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "acr_test",
      "object": "account_collection",
      "created": 1627210800,
      "account_collection": null,
      "amount": 40000,
      "currency": "gbp",
      "description": null,
      "destination_owner_payment_refund": null,
      "owner_balance_transaction": null,
      "owner": null,
      "tax": 0,
      "tax_behavior": "exclusive",
      "tax_percent": 0,
      "total": 0,
      "unit": null
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

List

Onboarding Sessions

Endpoints

POST    /v1/owners/:id/onboarding

An onboarding session represents your owner's session for completing their required information for compliance and identity verification.

The onboarding session object

The onboarding session object

{
  "id": "oos_test",
  "object": "onboarding_session",
  "created": 1627210800,
  "options": {
    "require_identity_verification": true
  },
  "owner": "owner_test",
  "return_url": "https://example.com/success",
  "type": "owner_onboarding",
  "unit_owner": null,
  "unit": "unit_test",
  "url": "https://owners.yorlet.com/onboarding/FlP02SduiwQ"
}

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 onboarding_session.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
options object
The options for the onboarding session.

options.require_identity_verification boolean
Whether or not to require identity verification during the onboarding session. Defaults to true.
owner stringexpandable
ID of the owner.
return_url string
The URL to redirect the owner after the onboarding session is completed or expires.
type string
The onboarding session type.
unit_owner stringexpandable
ID of the unit owner.
unit stringexpandable
ID of the unit.
url string

Create an onboarding session

POST /v1/owners/:id/onboarding

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

Example Response

{
  "id": "oos_test",
  "object": "onboarding_session",
  "created": 1627210800,
  "options": {
    "require_identity_verification": true
  },
  "owner": "owner_test",
  "return_url": "https://example.com/success",
  "type": "owner_onboarding",
  "unit_owner": null,
  "unit": "unit_test",
  "url": "https://owners.yorlet.com/onboarding/FlP02SduiwQ"
}

Creates an onboarding session object.

Parameters

type required
Can be unit_owner_onboarding or owner_onboarding.
options optional object
A set of options for the session.

options.require_identity_verification optional boolean
Require the identity verification step. Defaults to true.
return_url optional
The URL to redirect the owner after the onboarding session is completed or expires.
send_email optional boolean
Whether or not to send an email to the owner with a link to the onboarding flow. Defaults to false.
unit_owner optional

Returns

Returns the onboarding session object if the request succeeded.

Owners

Endpoints

POST    /v1/owners
GET     /v1/owners/:id
POST    /v1/owners/:id
DELETE  /v1/owners/:id
GET     /v1/owners

The API allows you to create, delete and update your owners. You can retrieve individual owners as well as a list of all your owners.

The owner object

The owner object

{
  "id": "owner_test",
  "object": "owner",
  "created": 1627210800,
  "archived": false,
  "archived_at": null,
  "balance": 0,
  "bank_account": null,
  "company": null,
  "country": null,
  "customer": null,
  "default_currency": null,
  "email": null,
  "external_account": null,
  "individual": {
    "id": "own_pers_test",
    "object": "owner_person",
    "created": 1723974546,
    "address": null,
    "dob": {},
    "email": null,
    "title": null,
    "first_name": null,
    "last_name": null,
    "metadata": {},
    "phone": null,
    "relationship": {
      "director": false,
      "executive": false,
      "owner": false,
      "percent_ownership": null,
      "representative": false,
      "title": null
    },
    "requirements": {
      "currently_due": [],
      "eventually_due": [],
      "pending_verification": []
    },
    "verification": {
      "identity_check": null,
      "status": "unverified"
    }
  },
  "metadata": {},
  "name": null,
  "next_statement_sequence": 1,
  "non_resident_tax_details": {
    "certificate": null,
    "certificate_date": null,
    "country": null,
    "status": "exempt"
  },
  "payouts_enabled": false,
  "portal_enabled": false,
  "requirements": {
    "currently_due": [],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [],
    "pending_verification": []
  },
  "settings": {
    "account_collections": {
      "platform_fee": 0
    },
    "maintenance": {
      "issue_categories": [],
      "issue_preferred_categories": []
    },
    "payout_receipts": {
      "email_to": null,
      "email_cc": [],
      "statement_descriptor": null,
      "send_email": true
    },
    "payout_schedule": {
      "interval": "month",
      "monthly_anchor": 31,
      "weekly_anchor": 5
    },
    "payouts": {
      "automatic_approval": false,
      "instant_payouts": false,
      "negative_payouts": false,
      "transaction_grouping": "all"
    }
  },
  "statement_prefix": null,
  "status": null,
  "tax_residency": null,
  "trading_as_name": null,
  "type": null
}

Attributes

id string
Unique identified for the object
object string
String representing the object's type. Objects of the same type share the same value Can be owner.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
archived boolean
Whether the owner is archived.
archived_at timestamp
Time at which the owner was archived.
address integer
The owner’s address.
balance integer
The owner’s current balance amount.
bank_account object
business_type undefined
Can be company or individual.
company string
Information about the company.
country string
The owner’s country.
customer stringexpandable
ID of the customer associated with this owner.
default_currency string
The owner’s default currency.
email string
The owner’s email address.
external_account stringexpandable
The owner’s external (bank) account.
individual objectexpandable
Information about the individual.
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 owner’s name.
next_statement_sequence integer
The sequence to be used on the owners’s next payout.
non_resident_tax_details object
The owner’s non resident tax status.
payouts_enabled boolean
Whether payouts are enabled for this owner.
portal_enabled boolean
requirements object
Information about the requirements for the owner.
settings object
Options for the owner.

settings.account_collections object
The owner’s account collections settings.

settings.account_collections.platform_fee integer
The platform fee for the owner.

settings.payout_receipts object
The owner’s payout settings.

settings.payout_receipts.email_to string
The email address to send payout statements to.

settings.payout_receipts.email_cc array
List of emails to CC in the payout statements email.

settings.payout_receipts.statement_descriptor string
The statement descriptor for the owner’s payouts.

settings.payout_schedule object
Settings for the owner’s payout schedule.

settings.payout_schedule.interval string
How frequently available funds are attached to payouts.

settings.payout_schedule.monthly_anchor integer
The day of the month when available funds are grouped.

settings.payout_schedule.weekly_anchor integer
The day of the week when available funds are grouped.

settings.payouts object
Settings for the owner’s payouts.

settings.payouts.automatic_approval string
Whether or not to allow automatic approvals for owner payouts.

settings.payouts.instant_payouts boolean
A Boolean indicating if instant payouts are enabled for this owner.

settings.payouts.negative_payouts boolean
A Boolean indicating if negative payouts are enabled for this owner.

settings.payouts.transaction_grouping string
How to group transactions for owner payouts. Can be all or per_unit.
statement_prefix object
The prefix used for owner payouts.
status string
The status of the owner. Can be compete, information_required or archived.
tax_residency string
The owner’s tax residency.
trading_as_name string
The owner’s trading name.
type string
The type of owner. Can be landlord or leaseholder.

Create an owner

POST /v1/owners

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

Example Response

{
  "id": "owner_test",
  "object": "owner",
  "created": 1627210800,
  "archived": false,
  "archived_at": null,
  "balance": 0,
  "bank_account": null,
  "company": null,
  "country": null,
  "customer": null,
  "default_currency": null,
  "email": null,
  "external_account": null,
  "individual": {
    "id": "own_pers_test",
    "object": "owner_person",
    "created": 1723974546,
    "address": null,
    "dob": {},
    "email": null,
    "title": null,
    "first_name": null,
    "last_name": null,
    "metadata": {},
    "phone": null,
    "relationship": {
      "director": false,
      "executive": false,
      "owner": false,
      "percent_ownership": null,
      "representative": false,
      "title": null
    },
    "requirements": {
      "currently_due": [],
      "eventually_due": [],
      "pending_verification": []
    },
    "verification": {
      "identity_check": null,
      "status": "unverified"
    }
  },
  "metadata": {},
  "name": null,
  "next_statement_sequence": 1,
  "non_resident_tax_details": {
    "certificate": null,
    "certificate_date": null,
    "country": null,
    "status": "exempt"
  },
  "payouts_enabled": false,
  "portal_enabled": false,
  "requirements": {
    "currently_due": [],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [],
    "pending_verification": []
  },
  "settings": {
    "account_collections": {
      "platform_fee": 0
    },
    "maintenance": {
      "issue_categories": [],
      "issue_preferred_categories": []
    },
    "payout_receipts": {
      "email_to": null,
      "email_cc": [],
      "statement_descriptor": null,
      "send_email": true
    },
    "payout_schedule": {
      "interval": "month",
      "monthly_anchor": 31,
      "weekly_anchor": 5
    },
    "payouts": {
      "automatic_approval": false,
      "instant_payouts": false,
      "negative_payouts": false,
      "transaction_grouping": "all"
    }
  },
  "statement_prefix": null,
  "status": null,
  "tax_residency": null,
  "trading_as_name": null,
  "type": null
}

Parameters

business_type required
The owner’s business type. Can be individual or company.
archived optional boolean
Whether the owner is archived.
company optional object
Information about the company.

company.address optional object
The company’s address.

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

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

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

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

company.address.postal_code optional
Postal code.

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

company.name optional
The company’s legal name.

company.phone optional
The company’s phone.

company.tax_id optional
The company’s business ID number.

company.vat_id optional
The company’s VAT number.
email optional
The email address of the owner.
individual optional object

individual.address optional object
The individual’s address.

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

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

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

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

individual.address.postal_code optional
Postal code.

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

individual.dob optional object
The individual’s date of birth.

individual.dob.day required integer
The day of birth, between 1 and 31.

individual.dob.month required integer
The month of birth, between 1 and 12.

individual.dob.year required integer
The four-digit year of birth.

individual.email optional
The individual’s email address.

individual.first_name optional
The individual’s first name.

individual.last_name optional
The individual’s last name.

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

individual.phone optional
The individual’s phone number.

individual.relationship optional object

individual.relationship.director optional boolean

individual.relationship.executive optional boolean

individual.relationship.owner optional boolean

individual.relationship.percent_ownership optional number

individual.relationship.representative optional boolean

individual.relationship.title optional

individual.title optional
The individual’s title. Can be mr, miss, mrs, ms, mx, m or dr.
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.
next_statement_sequence optional integer
The sequence to be used on the owners’s next payout. Defaults to 1.
non_resident_tax_details optional object
The owner’s non resident tax status.

non_resident_tax_details.certificate optional

non_resident_tax_details.certificate_date optional

non_resident_tax_details.country optional
Can be GB.
settings optional object
Options for the owner.

settings.account_collections optional object
The owners’s account collection settings.

settings.account_collections.platform_fee optional number
The platform fee to be charged on the owner’s account.

settings.maintenance optional object
The owners’s maintenance settings.

settings.maintenance.issue_categories optional array
The categories of maintenance issues the owner is responsible for.

settings.maintenance.issue_preferred_categories optional array
The preferred categories of maintenance issues the owner is responsible for.

settings.payout_receipts optional object
The owners’s payout receipt settings.

settings.payout_receipts.email_cc optional array
List of emails to CC in the statements email.

settings.payout_receipts.email_to optional
The email address to send statements to.

settings.payout_receipts.send_email optional boolean
Whether or not to send an email to the owner with a payout receipt

settings.payout_receipts.statement_descriptor optional
The statement descriptor to be used on the owner’s payouts.

settings.payout_schedule optional object
Settings for the owner’s payout schedule.

settings.payout_schedule.interval optional
How frequently available funds are attached to payouts. Default is daily.

settings.payout_schedule.monthly_anchor optional integer
The day of the month when available funds are grouped. Can be between 1-31.

settings.payout_schedule.weekly_anchor optional integer
The day of the week when available funds are grouped. Can only be a weekday 1-5, 1=monday, 2=tuesday, etc.

settings.payouts optional object
The owners’s payout settings.

settings.payouts.automatic_approval optional boolean
Whether or not to allow automatic approvals for owner payouts.

settings.payouts.instant_payouts optional boolean
Whether or not instant payouts are enabled for this owner.

settings.payouts.negative_payouts optional boolean
Whether or not negative payouts are enabled for this owner.

settings.payouts.transaction_grouping optional
Whether or not to create new payouts per unit for owner payouts. Can be all or per_unit.
statement_prefix optional
The prefix used for owner payouts.
tax_residency optional
The owner’s tax residency.
trading_as_name optional
The customer-facing name.
type optional
The owner’s type. Can be freeholder, landlord, leaseholder or supplier.

Returns

Returns the owner object if the request succeeded.

Retrieve an owner

GET /v1/owners/:id

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

Example Response

{
  "id": "owner_test",
  "object": "owner",
  "created": 1627210800,
  "archived": false,
  "archived_at": null,
  "balance": 0,
  "bank_account": null,
  "company": null,
  "country": null,
  "customer": null,
  "default_currency": null,
  "email": null,
  "external_account": null,
  "individual": {
    "id": "own_pers_test",
    "object": "owner_person",
    "created": 1723974546,
    "address": null,
    "dob": {},
    "email": null,
    "title": null,
    "first_name": null,
    "last_name": null,
    "metadata": {},
    "phone": null,
    "relationship": {
      "director": false,
      "executive": false,
      "owner": false,
      "percent_ownership": null,
      "representative": false,
      "title": null
    },
    "requirements": {
      "currently_due": [],
      "eventually_due": [],
      "pending_verification": []
    },
    "verification": {
      "identity_check": null,
      "status": "unverified"
    }
  },
  "metadata": {},
  "name": null,
  "next_statement_sequence": 1,
  "non_resident_tax_details": {
    "certificate": null,
    "certificate_date": null,
    "country": null,
    "status": "exempt"
  },
  "payouts_enabled": false,
  "portal_enabled": false,
  "requirements": {
    "currently_due": [],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [],
    "pending_verification": []
  },
  "settings": {
    "account_collections": {
      "platform_fee": 0
    },
    "maintenance": {
      "issue_categories": [],
      "issue_preferred_categories": []
    },
    "payout_receipts": {
      "email_to": null,
      "email_cc": [],
      "statement_descriptor": null,
      "send_email": true
    },
    "payout_schedule": {
      "interval": "month",
      "monthly_anchor": 31,
      "weekly_anchor": 5
    },
    "payouts": {
      "automatic_approval": false,
      "instant_payouts": false,
      "negative_payouts": false,
      "transaction_grouping": "all"
    }
  },
  "statement_prefix": null,
  "status": null,
  "tax_residency": null,
  "trading_as_name": null,
  "type": null
}

Parameters

No parameters

Returns

Returns an owner object if a valid identifier was provided.

Update an owner

POST /v1/owners/:id

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

Example Response

{
  "id": "owner_test",
  "object": "owner",
  "created": 1627210800,
  "archived": false,
  "archived_at": null,
  "balance": 0,
  "bank_account": null,
  "company": null,
  "country": null,
  "customer": null,
  "default_currency": null,
  "email": null,
  "external_account": null,
  "individual": {
    "id": "own_pers_test",
    "object": "owner_person",
    "created": 1723974546,
    "address": null,
    "dob": {},
    "email": null,
    "title": null,
    "first_name": null,
    "last_name": null,
    "metadata": {},
    "phone": null,
    "relationship": {
      "director": false,
      "executive": false,
      "owner": false,
      "percent_ownership": null,
      "representative": false,
      "title": null
    },
    "requirements": {
      "currently_due": [],
      "eventually_due": [],
      "pending_verification": []
    },
    "verification": {
      "identity_check": null,
      "status": "unverified"
    }
  },
  "metadata": {},
  "name": null,
  "next_statement_sequence": 1,
  "non_resident_tax_details": {
    "certificate": null,
    "certificate_date": null,
    "country": null,
    "status": "exempt"
  },
  "payouts_enabled": false,
  "portal_enabled": false,
  "requirements": {
    "currently_due": [],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [],
    "pending_verification": []
  },
  "settings": {
    "account_collections": {
      "platform_fee": 0
    },
    "maintenance": {
      "issue_categories": [],
      "issue_preferred_categories": []
    },
    "payout_receipts": {
      "email_to": null,
      "email_cc": [],
      "statement_descriptor": null,
      "send_email": true
    },
    "payout_schedule": {
      "interval": "month",
      "monthly_anchor": 31,
      "weekly_anchor": 5
    },
    "payouts": {
      "automatic_approval": false,
      "instant_payouts": false,
      "negative_payouts": false,
      "transaction_grouping": "all"
    }
  },
  "statement_prefix": null,
  "status": null,
  "tax_residency": null,
  "trading_as_name": null,
  "type": null
}

Parameters

archived optional boolean
Whether the owner is archived.
business_type optional
The owner’s business type. Can be individual or company.
company optional object
Information about the company.

company.address optional object
The company’s address.

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

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

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

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

company.address.postal_code optional
Postal code.

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

company.name optional
The company’s legal name.

company.phone optional
The company’s phone.

company.tax_id optional
The company’s business ID number.

company.vat_id optional
The company’s VAT number.
email optional
The email address of the owner.
individual optional object

individual.address optional object
The individual’s address.

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

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

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

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

individual.address.postal_code optional
Postal code.

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

individual.dob optional object
The individual’s date of birth.

individual.dob.day required integer
The day of birth, between 1 and 31.

individual.dob.month required integer
The month of birth, between 1 and 12.

individual.dob.year required integer
The four-digit year of birth.

individual.email optional
The individual’s email address.

individual.first_name optional
The individual’s first name.

individual.last_name optional
The individual’s last name.

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

individual.phone optional
The individual’s phone number.

individual.relationship optional object

individual.relationship.director optional boolean

individual.relationship.executive optional boolean

individual.relationship.owner optional boolean

individual.relationship.percent_ownership optional number

individual.relationship.representative optional boolean

individual.relationship.title optional

individual.title optional
The individual’s title. Can be mr, miss, mrs, ms, mx, m or dr.
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.
next_statement_sequence optional integer
The sequence to be used on the owners’s next payout. Defaults to 1.
non_resident_tax_details optional object
The owner’s non resident tax status.

non_resident_tax_details.certificate optional

non_resident_tax_details.certificate_date optional

non_resident_tax_details.country optional
Can be GB.
settings optional object
Options for the owner.

settings.account_collections optional object
The owners’s account collection settings.

settings.account_collections.platform_fee optional number
The platform fee to be charged on the owner’s account.

settings.maintenance optional object
The owners’s maintenance settings.

settings.maintenance.issue_categories optional array
The categories of maintenance issues the owner is responsible for.

settings.maintenance.issue_preferred_categories optional array
The preferred categories of maintenance issues the owner is responsible for.

settings.payout_receipts optional object
The owners’s payout receipt settings.

settings.payout_receipts.email_cc optional array
List of emails to CC in the statements email.

settings.payout_receipts.email_to optional
The email address to send statements to.

settings.payout_receipts.send_email optional boolean
Whether or not to send an email to the owner with a payout receipt

settings.payout_receipts.statement_descriptor optional
The statement descriptor to be used on the owner’s payouts.

settings.payout_schedule optional object
Settings for the owner’s payout schedule.

settings.payout_schedule.interval optional
How frequently available funds are attached to payouts. Default is daily.

settings.payout_schedule.monthly_anchor optional integer
The day of the month when available funds are grouped. Can be between 1-31.

settings.payout_schedule.weekly_anchor optional integer
The day of the week when available funds are grouped. Can only be a weekday 1-5, 1=monday, 2=tuesday, etc.

settings.payouts optional object
The owners’s payout settings.

settings.payouts.automatic_approval optional boolean
Whether or not to allow automatic approvals for owner payouts.

settings.payouts.instant_payouts optional boolean
Whether or not instant payouts are enabled for this owner.

settings.payouts.negative_payouts optional boolean
Whether or not negative payouts are enabled for this owner.

settings.payouts.transaction_grouping optional
Whether or not to create new payouts per unit for owner payouts. Can be all or per_unit.
statement_prefix optional
The prefix used for owner payouts.
tax_residency optional
The owner’s tax residency.
trading_as_name optional
The customer-facing name.
type optional
The owner’s type. Can be freeholder, landlord, leaseholder or supplier.

Returns

Returns the owner object if the update succeeded.

Delete an owner

DELETE /v1/owners/:id

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

Example Response

{
  "id": "owner_test",
  "object": "owner",
  "deleted": true
}

Parameters

No parameters

Returns

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

List all owners

GET /v1/owners

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "owner_test",
      "object": "owner",
      "created": 1627210800,
      "archived": false,
      "archived_at": null,
      "balance": 0,
      "bank_account": null,
      "company": null,
      "country": null,
      "customer": null,
      "default_currency": null,
      "email": null,
      "external_account": null,
      "individual": {
        "id": "own_pers_test",
        "object": "owner_person",
        "created": 1723974546,
        "address": null,
        "dob": {},
        "email": null,
        "title": null,
        "first_name": null,
        "last_name": null,
        "metadata": {},
        "phone": null,
        "relationship": {
          "director": false,
          "executive": false,
          "owner": false,
          "percent_ownership": null,
          "representative": false,
          "title": null
        },
        "requirements": {
          "currently_due": [],
          "eventually_due": [],
          "pending_verification": []
        },
        "verification": {
          "identity_check": null,
          "status": "unverified"
        }
      },
      "metadata": {},
      "name": null,
      "next_statement_sequence": 1,
      "non_resident_tax_details": {
        "certificate": null,
        "certificate_date": null,
        "country": null,
        "status": "exempt"
      },
      "payouts_enabled": false,
      "portal_enabled": false,
      "requirements": {
        "currently_due": [],
        "disabled_reason": null,
        "errors": [],
        "eventually_due": [],
        "pending_verification": []
      },
      "settings": {
        "account_collections": {
          "platform_fee": 0
        },
        "maintenance": {
          "issue_categories": [],
          "issue_preferred_categories": []
        },
        "payout_receipts": {
          "email_to": null,
          "email_cc": [],
          "statement_descriptor": null,
          "send_email": true
        },
        "payout_schedule": {
          "interval": "month",
          "monthly_anchor": 31,
          "weekly_anchor": 5
        },
        "payouts": {
          "automatic_approval": false,
          "instant_payouts": false,
          "negative_payouts": false,
          "transaction_grouping": "all"
        }
      },
      "statement_prefix": null,
      "status": null,
      "tax_residency": null,
      "trading_as_name": null,
      "type": null
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

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

Owner Balance Transactions

Endpoints

GET     /v1/owner_balance_transactions/:id
POST    /v1/owner_balance_transactions/:id
GET     /v1/owner_balance_transactions

The owner balance transaction object

The owner balance transaction object

{
  "id": "obtxn_test",
  "object": "owner_balance_transaction",
  "created": 1627210800,
  "amount": 40000,
  "available_on": null,
  "currency": "gbp",
  "description": null,
  "owner": null,
  "owner_payout": null,
  "reconciled_owner_payout": null,
  "source": null,
  "source_object": null,
  "tax": 0,
  "tax_percent": 0,
  "visible_to_owner": true
}

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 owner_balance_transaction.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
amount integer
available_on timestamp
Time at which the transaction will be available. Measured in seconds since the Unix epoch.
currency string
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html).
description string
An arbitrary string attached to the object. Often useful for displaying to users.
owner string
ID of the owner this owner balance transaction is associated with.
owner_payout stringexpandable
ID of the payout this owner balance transaction is associated with.
reconciled_owner_payout stringexpandable
source string
source_object string
tax integer
.
tax_percent integer
type string
The transaction type. Can be or .
visible_to_owner boolean

Retrieve an owner balance transaction

GET /v1/owner_balance_transactions/:id

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

Example Response

{
  "id": "obtxn_test",
  "object": "owner_balance_transaction",
  "created": 1627210800,
  "amount": 40000,
  "available_on": null,
  "currency": "gbp",
  "description": null,
  "owner": null,
  "owner_payout": null,
  "reconciled_owner_payout": null,
  "source": null,
  "source_object": null,
  "tax": 0,
  "tax_percent": 0,
  "visible_to_owner": true
}

Parameters

No parameters

Returns

Returns an owner balance transaction object if a valid identifier was provided

Update a balance transaction

POST /v1/owner_balance_transactions/:id

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

Example Response

{
  "id": "obtxn_test",
  "object": "owner_balance_transaction",
  "created": 1627210800,
  "amount": 40000,
  "available_on": null,
  "currency": "gbp",
  "description": null,
  "owner": null,
  "owner_payout": null,
  "reconciled_owner_payout": null,
  "source": null,
  "source_object": null,
  "tax": 0,
  "tax_percent": 0,
  "visible_to_owner": true
}

Change whether the owner balance transaction can be seen on statements and payout receipts by owners.

Parameters

No parameters

Returns

List

List all owner balance transactions

GET /v1/owner_balance_transactions

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "obtxn_test",
      "object": "owner_balance_transaction",
      "created": 1627210800,
      "amount": 40000,
      "available_on": null,
      "currency": "gbp",
      "description": null,
      "owner": null,
      "owner_payout": null,
      "reconciled_owner_payout": null,
      "source": null,
      "source_object": null,
      "tax": 0,
      "tax_percent": 0,
      "visible_to_owner": true
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

List

Owner Payments

Endpoints

GET     /v1/owner_payments/:id
POST    /v1/owner_payments/:id
GET     /v1/owner_payments

The owner payment object

The owner payment object

{
  "id": "opy_test",
  "object": "owner_payment",
  "created": 1627210800,
  "amount": 40000,
  "currency": "gbp",
  "description": null,
  "owner": "owner_test",
  "owner_balance_transaction": null,
  "period": {
    "end": null,
    "start": null
  },
  "refunded": false,
  "source_account_collection": null,
  "source_transfer": null,
  "status": null,
  "unit": "unit_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 owner_payment.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
account_collection stringexpandable
The account collection that was automatically created by this owner payment.
amount integer
Amount for this payment. This must be a positive integer in the smallest currency unit (e.g., 100 pennies for a charge of £1.00).
amount_refunded integer
Amount refunded from this payment.
currency string
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html).
description string
An arbitrary string attached to the object. Often useful for displaying to users.
owner stringexpandable
ID of the owner this payment is for.
owner_balance_transaction stringexpandable
ID of the owner balance transaction that describes the impact of this payment on their account balance (not including refunds).
period object
The period for which the payment was made.

period.end integer
End of the payment's billing period.

period.start integer
Start of the payment's billing period.
refunded boolean
Whether or not the payment has been fully refunded.
source_account_collection stringexpandable
The account collection ID which created this owner payment. Only present if the payment came from another owner account.
source_transfer stringexpandable
The transfer ID which created this owner payment. Only present if the payment was created from a transfer.
status string
The status of the payment.
unit stringexpandable
ID of the unit this payment is for.

Get an owner payment

GET /v1/owner_payments/:id

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

Example Response

{
  "id": "opy_test",
  "object": "owner_payment",
  "created": 1627210800,
  "amount": 40000,
  "currency": "gbp",
  "description": null,
  "owner": "owner_test",
  "owner_balance_transaction": null,
  "period": {
    "end": null,
    "start": null
  },
  "refunded": false,
  "source_account_collection": null,
  "source_transfer": null,
  "status": null,
  "unit": "unit_test"
}

Parameters

No parameters

Returns

Returns an owner payment object if a valid identifier was provided

Update an owner payment

POST /v1/owner_payments/:id

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

Example Response

{
  "id": "opy_test",
  "object": "owner_payment",
  "created": 1627210800,
  "amount": 40000,
  "currency": "gbp",
  "description": null,
  "owner": "owner_test",
  "owner_balance_transaction": null,
  "period": {
    "end": null,
    "start": null
  },
  "refunded": false,
  "source_account_collection": null,
  "source_transfer": null,
  "status": null,
  "unit": "unit_test"
}

Parameters

description optional
The description for the invoice item, to be displayed to the customer.
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.
period optional object
A hash of the period this owner payment relates to.

period.end optional
The period end date. Measured in seconds since the Unix epoch.

period.start optional
The period start date. Measured in seconds since the Unix epoch.

Returns

Returns an updated owner payment object if a valid identifier was provided

List all owner payments

GET /v1/owner_payments

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "opy_test",
      "object": "owner_payment",
      "created": 1627210800,
      "amount": 40000,
      "currency": "gbp",
      "description": null,
      "owner": "owner_test",
      "owner_balance_transaction": null,
      "period": {
        "end": null,
        "start": null
      },
      "refunded": false,
      "source_account_collection": null,
      "source_transfer": null,
      "status": null,
      "unit": "unit_test"
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

List

Owner Payouts

Endpoints

POST    /v1/owner_payouts
POST    /v1/owner_payouts/preview
GET     /v1/owner_payouts/:id
POST    /v1/owner_payouts/:id/approve
POST    /v1/owner_payouts/:id/approve/preview
POST    /v1/owner_payouts/:id/cancel
POST    /v1/owner_payouts/:id/mark_failed
POST    /v1/owner_payouts/:id/mark_paid
POST    /v1/owner_payouts/:id/send_receipt
GET     /v1/owner_payouts

The owner payout object

The owner payout object

{
  "id": "opo_test",
  "object": "owner_payout",
  "created": 1627210800,
  "amount": 40000,
  "approved_at": null,
  "canceled_at": null,
  "client_secret": "opo_test_secret_undefined",
  "currency": "gbp",
  "description": null,
  "destination": null,
  "destination_details": null,
  "failed_at": null,
  "failure_code": null,
  "failure_message": null,
  "failure_owner_balance_transaction": null,
  "hosted_payment_url": null,
  "last_approval_error": null,
  "metadata": {},
  "method": "manual",
  "net": 0,
  "number": null,
  "owner": "owner_test",
  "owner_balance_transaction": null,
  "owner_non_resident_tax": {
    "deduction": 0,
    "details": null,
    "taxable_amount": null
  },
  "owner_tax_residency": null,
  "paid_at": null,
  "payment_run": null,
  "statement_descriptor": "OWNER PAYOUT",
  "status": "draft",
  "transaction": null,
  "type": "owner",
  "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 owner_payout.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
amount integer
Amount to be transfered to the bank account.
approved_at timestamp
Time at which the object was approved. Measured in seconds since the Unix epoch.
canceled_at timestamp
Time at which the object was canceled. Measured in seconds since the Unix epoch.
client_secret string
The client secret can be used to access the statement PDF for the owner payout.
currency string
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html).
description string
destination stringexpandable
destination_details string
failed_at timestamp
Time at which the object was failed. Measured in seconds since the Unix epoch.
failure_code string
failure_message string
failure_owner_balance_transaction stringexpandable
hosted_payment_url string
The URL for the hosted payment page, which allows customers to view and pay a negative payout.
last_approval_error string
The last approval error on this owner payout.
metadata string
method string
net integer
number string
owner stringexpandable
owner_balance_transaction stringexpandable
owner_non_resident_tax string
owner_tax_residency string
paid_at timestamp
Time at which the object was paid. Measured in seconds since the Unix epoch.
payment_run stringexpandable
statement_descriptor string
status undefined
The status of the owner payout. Can be pending, in_transit, succeeded, failed or cancelled.
transaction stringexpandable
The ID of the transaction associated with this owner payout.
type undefined
The type of the owner payout. Can be owner or vendor.
unit stringexpandable

Create an owner payout

POST /v1/owner_payouts

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

Example Response

{
  "id": "opo_test",
  "object": "owner_payout",
  "created": 1627210800,
  "amount": 40000,
  "approved_at": null,
  "canceled_at": null,
  "client_secret": "opo_test_secret_undefined",
  "currency": "gbp",
  "description": null,
  "destination": null,
  "destination_details": null,
  "failed_at": null,
  "failure_code": null,
  "failure_message": null,
  "failure_owner_balance_transaction": null,
  "hosted_payment_url": null,
  "last_approval_error": null,
  "metadata": {},
  "method": "manual",
  "net": 0,
  "number": null,
  "owner": "owner_test",
  "owner_balance_transaction": null,
  "owner_non_resident_tax": {
    "deduction": 0,
    "details": null,
    "taxable_amount": null
  },
  "owner_tax_residency": null,
  "paid_at": null,
  "payment_run": null,
  "statement_descriptor": "OWNER PAYOUT",
  "status": "draft",
  "transaction": null,
  "type": "owner",
  "unit": null
}

Parameters

owner required
description optional
expand optional array
Can be external_account.
method optional
Can be automatic or manual.
options optional object

options.apply_unit_restriction optional boolean
statement_descriptor optional
unit optional

Returns

List

Preview an owner payout

POST /v1/owner_payouts/preview

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

Example Response

{
  "id": "opo_test",
  "object": "owner_payout",
  "created": 1627210800,
  "amount": 40000,
  "approved_at": null,
  "canceled_at": null,
  "client_secret": "opo_test_secret_undefined",
  "currency": "gbp",
  "description": null,
  "destination": null,
  "destination_details": null,
  "failed_at": null,
  "failure_code": null,
  "failure_message": null,
  "failure_owner_balance_transaction": null,
  "hosted_payment_url": null,
  "last_approval_error": null,
  "metadata": {},
  "method": "manual",
  "net": 0,
  "number": null,
  "owner": "owner_test",
  "owner_balance_transaction": null,
  "owner_non_resident_tax": {
    "deduction": 0,
    "details": null,
    "taxable_amount": null
  },
  "owner_tax_residency": null,
  "paid_at": null,
  "payment_run": null,
  "statement_descriptor": "OWNER PAYOUT",
  "status": "draft",
  "transaction": null,
  "type": "owner",
  "unit": null
}

Parameters

No parameters

Returns

Retrieve an owner payout

GET /v1/owner_payouts/:id

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

Example Response

{
  "id": "opo_test",
  "object": "owner_payout",
  "created": 1627210800,
  "amount": 40000,
  "approved_at": null,
  "canceled_at": null,
  "client_secret": "opo_test_secret_undefined",
  "currency": "gbp",
  "description": null,
  "destination": null,
  "destination_details": null,
  "failed_at": null,
  "failure_code": null,
  "failure_message": null,
  "failure_owner_balance_transaction": null,
  "hosted_payment_url": null,
  "last_approval_error": null,
  "metadata": {},
  "method": "manual",
  "net": 0,
  "number": null,
  "owner": "owner_test",
  "owner_balance_transaction": null,
  "owner_non_resident_tax": {
    "deduction": 0,
    "details": null,
    "taxable_amount": null
  },
  "owner_tax_residency": null,
  "paid_at": null,
  "payment_run": null,
  "statement_descriptor": "OWNER PAYOUT",
  "status": "draft",
  "transaction": null,
  "type": "owner",
  "unit": null
}

Parameters

No parameters

Returns

Approve an owner payout

POST /v1/owner_payouts/:id/approve

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

Example Response

{
  "id": "opo_test",
  "object": "owner_payout",
  "created": 1627210800,
  "amount": 40000,
  "approved_at": null,
  "canceled_at": null,
  "client_secret": "opo_test_secret_undefined",
  "currency": "gbp",
  "description": null,
  "destination": null,
  "destination_details": null,
  "failed_at": null,
  "failure_code": null,
  "failure_message": null,
  "failure_owner_balance_transaction": null,
  "hosted_payment_url": null,
  "last_approval_error": null,
  "metadata": {},
  "method": "manual",
  "net": 0,
  "number": null,
  "owner": "owner_test",
  "owner_balance_transaction": null,
  "owner_non_resident_tax": {
    "deduction": 0,
    "details": null,
    "taxable_amount": null
  },
  "owner_tax_residency": null,
  "paid_at": null,
  "payment_run": null,
  "statement_descriptor": "OWNER PAYOUT",
  "status": "draft",
  "transaction": null,
  "type": "owner",
  "unit": null
}

Parameters

No parameters

Returns

Preview an owner payout approval

POST /v1/owner_payouts/:id/approve/preview

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

Example Response

{
  "id": "opo_test",
  "object": "owner_payout",
  "created": 1627210800,
  "amount": 40000,
  "approved_at": null,
  "canceled_at": null,
  "client_secret": "opo_test_secret_undefined",
  "currency": "gbp",
  "description": null,
  "destination": null,
  "destination_details": null,
  "failed_at": null,
  "failure_code": null,
  "failure_message": null,
  "failure_owner_balance_transaction": null,
  "hosted_payment_url": null,
  "last_approval_error": null,
  "metadata": {},
  "method": "manual",
  "net": 0,
  "number": null,
  "owner": "owner_test",
  "owner_balance_transaction": null,
  "owner_non_resident_tax": {
    "deduction": 0,
    "details": null,
    "taxable_amount": null
  },
  "owner_tax_residency": null,
  "paid_at": null,
  "payment_run": null,
  "statement_descriptor": "OWNER PAYOUT",
  "status": "draft",
  "transaction": null,
  "type": "owner",
  "unit": null
}

Parameters

No parameters

Returns

Cancel an owner payout

POST /v1/owner_payouts/:id/cancel

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

Example Response

{
  "id": "opo_test",
  "object": "owner_payout",
  "created": 1627210800,
  "amount": 40000,
  "approved_at": null,
  "canceled_at": null,
  "client_secret": "opo_test_secret_undefined",
  "currency": "gbp",
  "description": null,
  "destination": null,
  "destination_details": null,
  "failed_at": null,
  "failure_code": null,
  "failure_message": null,
  "failure_owner_balance_transaction": null,
  "hosted_payment_url": null,
  "last_approval_error": null,
  "metadata": {},
  "method": "manual",
  "net": 0,
  "number": null,
  "owner": "owner_test",
  "owner_balance_transaction": null,
  "owner_non_resident_tax": {
    "deduction": 0,
    "details": null,
    "taxable_amount": null
  },
  "owner_tax_residency": null,
  "paid_at": null,
  "payment_run": null,
  "statement_descriptor": "OWNER PAYOUT",
  "status": "draft",
  "transaction": null,
  "type": "owner",
  "unit": null
}

Parameters

No parameters

Returns

Mark an owner payout as failed

POST /v1/owner_payouts/:id/mark_failed

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

Example Response

{
  "id": "opo_test",
  "object": "owner_payout",
  "created": 1627210800,
  "amount": 40000,
  "approved_at": null,
  "canceled_at": null,
  "client_secret": "opo_test_secret_undefined",
  "currency": "gbp",
  "description": null,
  "destination": null,
  "destination_details": null,
  "failed_at": null,
  "failure_code": null,
  "failure_message": null,
  "failure_owner_balance_transaction": null,
  "hosted_payment_url": null,
  "last_approval_error": null,
  "metadata": {},
  "method": "manual",
  "net": 0,
  "number": null,
  "owner": "owner_test",
  "owner_balance_transaction": null,
  "owner_non_resident_tax": {
    "deduction": 0,
    "details": null,
    "taxable_amount": null
  },
  "owner_tax_residency": null,
  "paid_at": null,
  "payment_run": null,
  "statement_descriptor": "OWNER PAYOUT",
  "status": "draft",
  "transaction": null,
  "type": "owner",
  "unit": null
}

Parameters

failure_code optional
Can be no_account.
failure_message optional

Returns

Mark an owner payout as paid

POST /v1/owner_payouts/:id/mark_paid

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

Example Response

{
  "id": "opo_test",
  "object": "owner_payout",
  "created": 1627210800,
  "amount": 40000,
  "approved_at": null,
  "canceled_at": null,
  "client_secret": "opo_test_secret_undefined",
  "currency": "gbp",
  "description": null,
  "destination": null,
  "destination_details": null,
  "failed_at": null,
  "failure_code": null,
  "failure_message": null,
  "failure_owner_balance_transaction": null,
  "hosted_payment_url": null,
  "last_approval_error": null,
  "metadata": {},
  "method": "manual",
  "net": 0,
  "number": null,
  "owner": "owner_test",
  "owner_balance_transaction": null,
  "owner_non_resident_tax": {
    "deduction": 0,
    "details": null,
    "taxable_amount": null
  },
  "owner_tax_residency": null,
  "paid_at": null,
  "payment_run": null,
  "statement_descriptor": "OWNER PAYOUT",
  "status": "draft",
  "transaction": null,
  "type": "owner",
  "unit": null
}

Parameters

paid_at optional
send_receipt optional boolean

Returns

Send an owner payout receipt

POST /v1/owner_payouts/:id/send_receipt

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

Example Response

{
  "id": "opo_test",
  "object": "owner_payout",
  "created": 1627210800,
  "amount": 40000,
  "approved_at": null,
  "canceled_at": null,
  "client_secret": "opo_test_secret_undefined",
  "currency": "gbp",
  "description": null,
  "destination": null,
  "destination_details": null,
  "failed_at": null,
  "failure_code": null,
  "failure_message": null,
  "failure_owner_balance_transaction": null,
  "hosted_payment_url": null,
  "last_approval_error": null,
  "metadata": {},
  "method": "manual",
  "net": 0,
  "number": null,
  "owner": "owner_test",
  "owner_balance_transaction": null,
  "owner_non_resident_tax": {
    "deduction": 0,
    "details": null,
    "taxable_amount": null
  },
  "owner_tax_residency": null,
  "paid_at": null,
  "payment_run": null,
  "statement_descriptor": "OWNER PAYOUT",
  "status": "draft",
  "transaction": null,
  "type": "owner",
  "unit": null
}

Parameters

Returns

List all owner payouts

GET /v1/owner_payouts

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "opo_test",
      "object": "owner_payout",
      "created": 1627210800,
      "amount": 40000,
      "approved_at": null,
      "canceled_at": null,
      "client_secret": "opo_test_secret_undefined",
      "currency": "gbp",
      "description": null,
      "destination": null,
      "destination_details": null,
      "failed_at": null,
      "failure_code": null,
      "failure_message": null,
      "failure_owner_balance_transaction": null,
      "hosted_payment_url": null,
      "last_approval_error": null,
      "metadata": {},
      "method": "manual",
      "net": 0,
      "number": null,
      "owner": "owner_test",
      "owner_balance_transaction": null,
      "owner_non_resident_tax": {
        "deduction": 0,
        "details": null,
        "taxable_amount": null
      },
      "owner_tax_residency": null,
      "paid_at": null,
      "payment_run": null,
      "statement_descriptor": "OWNER PAYOUT",
      "status": "draft",
      "transaction": null,
      "type": "owner",
      "unit": null
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

List

Tax Forms

Endpoints

POST    /v1/tax_forms
GET     /v1/tax_forms/:id
DELETE  /v1/tax_forms/:id
GET     /v1/tax_forms

The tax form object

The tax form object

{
  "id": "tax_form_test",
  "object": "tax_form",
  "created": 1627210800,
  "client_secret": "tax_form_test_secret_token",
  "currency": "gbp",
  "description": null,
  "metadata": {},
  "nrl6": {
    "collected": 12000,
    "refunded": 0
  },
  "period": {
    "end": 1723974546,
    "start": 1723974546
  },
  "options": {
    "quarter": null,
    "year": 2021
  },
  "owner": null,
  "type": "nrl6"
}

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 tax_form.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
client_secret string
The client secret can be used to access the PDF for the tax form.
currency string
Three-letter ISO currency code, in lowercase.
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.
nrl6 object
The amount collected and refunded for the NRL6 tax form.

nrl6.collected integer
The amount of tax collected for the tax form.

nrl6.refunded integer
The amount of tax refunded for the tax form.
nrlq object
The amount collected and refunded for the NRLQ tax form.

nrlq.collected integer
The amount of tax collected for the tax form.

nrlq.refunded integer
The amount of tax refunded for the tax form.
nrly object
The amount collected and refunded for the NRLY tax form.

nrly.collected integer
The amount of tax collected for the tax form.

nrly.refunded integer
The amount of tax refunded for the tax form.
period object
The start and end dates of the tax form.
options object
The options for the tax form.

options.quarter integer
The quarter of the tax form.

options.year integer
The year of the tax form.
owner stringexpandable
The ID of the owner this tax form is for.
status string
The status of the tax form. Can be ready, needs_attention or filed.
type string
The type of the tax form. Can be nrl6, nrlq or nrly.

Create a tax form

POST /v1/tax_forms

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

Example Response

{
  "id": "tax_form_test",
  "object": "tax_form",
  "created": 1627210800,
  "client_secret": "tax_form_test_secret_token",
  "currency": "gbp",
  "description": null,
  "metadata": {},
  "nrl6": {
    "collected": 12000,
    "refunded": 0
  },
  "period": {
    "end": 1723974546,
    "start": 1723974546
  },
  "options": {
    "quarter": null,
    "year": 2021
  },
  "owner": null,
  "type": "nrl6"
}

Parameters

options required object
A set of options for the tax form.

options.year required integer
The tax year for the tax form. Can be 2025, 2024, 2023, 2022 or 2021.

options.quarter optional integer
The tax quarter for the tax form. Can be 1, 2, 3 or 4.
type required
The tax form type. Can be nrl6, nrlq or nrly.
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.
owner optional
The ID of the owner to create the tax form for. Only allowed when the tax form type is nrl6.

Returns

Returns a tax form object if successful.

Retrieve a tax form

GET /v1/tax_forms/:id

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

Example Response

{
  "id": "tax_form_test",
  "object": "tax_form",
  "created": 1627210800,
  "client_secret": "tax_form_test_secret_token",
  "currency": "gbp",
  "description": null,
  "metadata": {},
  "nrl6": {
    "collected": 12000,
    "refunded": 0
  },
  "period": {
    "end": 1723974546,
    "start": 1723974546
  },
  "options": {
    "quarter": null,
    "year": 2021
  },
  "owner": null,
  "type": "nrl6"
}

Parameters

No parameters

Returns

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

Delete a tax report

DELETE /v1/tax_forms/:id

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

Example Response

{
  "id": "tax_form_test",
  "object": "tax_form",
  "deleted": true
}

Parameters

No parameters

Returns

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

List all tax forms

GET /v1/tax_forms

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "tax_form_test",
      "object": "tax_form",
      "created": 1627210800,
      "client_secret": "tax_form_test_secret_token",
      "currency": "gbp",
      "description": null,
      "metadata": {},
      "nrl6": {
        "collected": 12000,
        "refunded": 0
      },
      "period": {
        "end": 1723974546,
        "start": 1723974546
      },
      "options": {
        "quarter": null,
        "year": 2021
      },
      "owner": null,
      "type": "nrl6"
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

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

Transfers

Endpoints

POST    /v1/transfers
GET     /v1/transfers/:id
GET     /v1/transfers/:id
GET     /v1/transfers

The transfer object

The transfer object

{
  "id": "tr_test",
  "object": "transfer",
  "created": 1627210800,
  "amount": 0,
  "balance_transaction": null,
  "destination": null,
  "destination_owner_payment": null,
  "source_invoice_item": null,
  "source_transaction": null,
  "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 transfer.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
amount integer
amount_reversed integer
balance_transaction stringexpandable
currency string
description string
destination stringexpandable
destination_owner_payment stringexpandable
reversed boolean
Whether the transfer has been fully reversed.
source_invoice_item stringexpandable
source_transaction stringexpandable
transfer_group string

Create a transfer

POST /v1/transfers

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

Example Response

{
  "id": "tr_test",
  "object": "transfer",
  "created": 1627210800,
  "amount": 0,
  "balance_transaction": null,
  "destination": null,
  "destination_owner_payment": null,
  "source_invoice_item": null,
  "source_transaction": null,
  "transfer_group": null
}

Parameters

amount required integer
currency required
Can be eur, gbp, sek or usd.
destination required
apply_unit_fees optional boolean
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.
owner_payment_data optional object

owner_payment_data.period optional object
A hash of the period this owner payment relates to.

owner_payment_data.period.end optional
The period end date. Measured in seconds since the Unix epoch.

owner_payment_data.period.start optional
The period start date. Measured in seconds since the Unix epoch.
reporting_type optional
Can be rent, deposit or other.
source_transaction optional
unit optional

Returns

Returns a transfer object if successful.

Retrieve a transfer

GET /v1/transfers/:id

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

Example Response

{
  "id": "tr_test",
  "object": "transfer",
  "created": 1627210800,
  "amount": 0,
  "balance_transaction": null,
  "destination": null,
  "destination_owner_payment": null,
  "source_invoice_item": null,
  "source_transaction": null,
  "transfer_group": null
}

Parameters

No parameters

Returns

Returns a transfer object if a valid identifier was provided.

Update a transfer

GET /v1/transfers/:id

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

Example Response

{
  "id": "tr_test",
  "object": "transfer",
  "created": 1627210800,
  "amount": 0,
  "balance_transaction": null,
  "destination": null,
  "destination_owner_payment": null,
  "source_invoice_item": null,
  "source_transaction": null,
  "transfer_group": null
}

Parameters

No parameters

Returns

Returns an updated transfer object if a valid identifier was provided.

List all transfers

GET /v1/transfers

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "tr_test",
      "object": "transfer",
      "created": 1627210800,
      "amount": 0,
      "balance_transaction": null,
      "destination": null,
      "destination_owner_payment": null,
      "source_invoice_item": null,
      "source_transaction": null,
      "transfer_group": null
    }
  ],
  "count": 1,
  "has_more": false
}

Parameters

No parameters

Returns

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

Platform Resources

Accounts

Endpoints

GET     /v1/accounts

The account object

The account object

{
  "id": "acct_test",
  "object": "account",
  "created": 1627210800,
  "address": {
    "line1": null,
    "line2": null,
    "city": null,
    "state": null,
    "postal_code": null,
    "country": null
  },
  "balance_enabled": false,
  "business_profile": {
    "address": null,
    "name": null,
    "support_email": null,
    "support_phone": null,
    "support_url": null,
    "url": null
  },
  "charges_enabled": false,
  "country": "GB",
  "default_currency": "gbp",
  "details_submitted": false,
  "invoice_settings": {
    "days_until_due": null,
    "supported_payment_methods": {
      "bacs_debit": true,
      "card": true,
      "gbp_credit_transfer": true,
      "sepa_debit": false
    }
  },
  "name": null,
  "payouts_enabled": false,
  "settings": {
    "bacs_debit_payments": {
      "display_name": null
    },
    "payments": {
      "statement_descriptor": null
    }
  },
  "settlement_currencies": []
}

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 account.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
address object
The account's address.
balance_enabled boolean
.
business_profile object
.

business_profile.address object

business_profile.name string

business_profile.support_email string

business_profile.support_phone string

business_profile.support_url string

business_profile.url string
business_type string
charges_enabled boolean
company object
country string
default_currency string
Three-letter ISO currency code, in lowercase. Must be a supported currency.
details_submitted boolean
.
individual object
invoice_settings object
name string
The building's name.
payouts_enabled boolean
.
settings object
settlement_currencies array
.

List all connected accounts

GET /v1/accounts

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "acct_test",
      "object": "account",
      "created": 1627210800,
      "address": {
        "line1": null,
        "line2": null,
        "city": null,
        "state": null,
        "postal_code": null,
        "country": null
      },
      "balance_enabled": false,
      "business_profile": {
        "address": null,
        "name": null,
        "support_email": null,
        "support_phone": null,
        "support_url": null,
        "url": null
      },
      "charges_enabled": false,
      "country": "GB",
      "default_currency": "gbp",
      "details_submitted": false,
      "invoice_settings": {
        "days_until_due": null,
        "supported_payment_methods": {
          "bacs_debit": true,
          "card": true,
          "gbp_credit_transfer": true,
          "sepa_debit": false
        }
      },
      "name": null,
      "payouts_enabled": false,
      "settings": {
        "bacs_debit_payments": {
          "display_name": null
        },
        "payments": {
          "statement_descriptor": null
        }
      },
      "settlement_currencies": []
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of accounts connected to your platform.

Parameters

No parameters

Returns

List

Webhook Resources

Webhook Endpoints

Endpoints

POST    /v1/webhook_endpoints
GET     /v1/webhook_endpoints/:id
POST    /v1/webhook_endpoints/:id
DELETE  /v1/webhook_endpoints/:id
GET     /v1/webhook_endpoints

You can configure webhook endpoints via the API to be notified about events that happen in your Yorlet account or connected accounts. You can see the full list of available events you can subscribe to here.

The webhook endpoint object

The webhook endpoint object

{
  "id": "wh_test",
  "object": "webhook_endpoint",
  "created": 1627210800,
  "connected_accounts": false,
  "description": null,
  "enabled_events": [],
  "metadata": {},
  "status": "enabled",
  "url": "https://example.com/webhook"
}

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 webhook_endpoint.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
connected_accounts object
Whether the webhook endpoint is for connected account events.
description string
An arbitrary string attached to the object. Often useful for displaying to users.
enabled_events array
The events this endpoint will receive.
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 webhook endpoint. Can be disabled or enabled.
url string
The url of the webhook endpoint.

Create a webhook endpoint

POST /v1/webhook_endpoints

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

Example Response

{
  "id": "wh_test",
  "object": "webhook_endpoint",
  "created": 1627210800,
  "connected_accounts": false,
  "description": null,
  "enabled_events": [],
  "metadata": {},
  "status": "enabled",
  "url": "https://example.com/webhook"
}

Creates a webhook endpoint.

Parameters

enabled_events required array
The list of events to enable for this endpoint. You can see the full list of available events here.
url required
The URL of the webhook endpoint.
connected_accounts optional boolean
Whether this endpoint should receive events from connected accounts, or from your account.
description optional
An optional description of what the webhook is used for.
disabled optional boolean
Disable the webhook endpoint if set to true.
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 webhook endpoint object if the request succeeded.

Retrieve a webhook endpoint

GET /v1/webhook_endpoints/:id

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

Example Response

{
  "id": "wh_test",
  "object": "webhook_endpoint",
  "created": 1627210800,
  "connected_accounts": false,
  "description": null,
  "enabled_events": [],
  "metadata": {},
  "status": "enabled",
  "url": "https://example.com/webhook"
}

Retrieves the webhook endpoint with the given ID.

Parameters

No parameters

Returns

Returns a unit object if a valid identifier was provided.

Update a webhook endpoint

POST /v1/webhook_endpoints/:id

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

Example Response

{
  "id": "wh_test",
  "object": "webhook_endpoint",
  "created": 1627210800,
  "connected_accounts": false,
  "description": null,
  "enabled_events": [],
  "metadata": {},
  "status": "enabled",
  "url": "https://example.com/webhook"
}

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

Parameters

description optional
An optional description of what the webhook is used for.
disabled optional boolean
Disable the webhook endpoint if set to true.
enabled_events optional array
The list of events to enable for this endpoint. You can see the full list of available events here.
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.
url optional
The URL of the webhook endpoint.

Returns

Returns the webhook endpoint object if the update succeeded.

Delete a webhook endpoint

DELETE /v1/webhook_endpoints/:id

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

Example Response

{
  "id": "wh_test",
  "object": "webhook_endpoint",
  "deleted": true
}

Permanently deletes a webhook endpoint. This cannot be undone.

Parameters

No parameters

Returns

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

List all webhook endpoints

GET /v1/webhook_endpoints

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

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "wh_test",
      "object": "webhook_endpoint",
      "created": 1627210800,
      "connected_accounts": false,
      "description": null,
      "enabled_events": [],
      "metadata": {},
      "status": "enabled",
      "url": "https://example.com/webhook"
    }
  ],
  "count": 1,
  "has_more": false
}

Returns a list of webhook endpoints. The webhook endpoints 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 webhook endpoints.