How do I use the V4 Applicants API to manage tenancy applications?

This documentation is intended for technical teams implementing the API integration. For general questions about application forms and non-technical support, contact support@agentos.com.

The Tenancy Applications API allows you to manage tenancy applications, including creating new prospects, submitting applications, and managing lettings property alerts.

Base URL

All API URLs are relative to: https://api.letmc.com/v4/applications

Prospect Controller

1. Create a tenancy application

Endpoint: POST /prospects/createTenancyApplication

Creates a new prospect and associated tenancy application in agentOS.

Required fields:

• BranchID — the branch the application is being submitted to
• Forename — applicant's first name
• Surname — applicant's last name
• EmailAddress — applicant's email address
• PropertyOID — the OID of the lettings property being applied for

Optional fields:

• Title — applicant's title
• MobilePhone / HomePhone / WorkPhone — contact numbers
• Message — any additional notes or message from the applicant

Behaviour: If a contact matching the email address already exists in the system, the application will be linked to that existing contact rather than creating a duplicate.

2. Submit tenancy application (inbox)

Endpoint: POST /prospects/submitTenancyApplicationInbox

Submits a tenancy application and places it into the agentOS inbox for processing by staff. This is the endpoint to use when you want a submitted application to appear as a task for the lettings team.

Required fields: Same as Create Tenancy Application.

Behaviour: Triggers a notification in the agentOS inbox, alerting staff that a new application requires attention.

3. Set up property alerts

Endpoint: POST /prospects/setupAlerts

Registers a prospective tenant for lettings property alerts based on their search criteria. When matching properties become available, alerts can be triggered automatically.

Required fields:

• BranchID
• Forename, Surname, EmailAddress
• Alert criteria (minimum rent, maximum rent, minimum bedrooms, property type, etc.)

4. Retrieve applicants

Endpoint: GET /prospects/applicants/{branchID}/{offset}/{count}

Returns a list of lettings applicants registered against a branch. Supports pagination using offset and count.

Sales Controller

Submit sales offer

Endpoint: POST /sales/submitOffer

Submits a sales offer against a sales instruction in agentOS.

Required fields:

• SalesInstructionID — the OID of the sales property
• Forename, Surname, EmailAddress — purchaser details
• OfferAmount — the offer amount in pence (e.g. £250,000 = 25000000)
• BranchID

Optional fields:

• Message — any notes accompanying the offer
• Contact numbers

Pagination

Endpoints that return collections use offset and count pagination. The maximum value for count is 1,000. To retrieve all records across a large dataset, increment offset by your chosen count value until fewer results than the count are returned, indicating you have reached the end of the dataset.

Example:

• First request: offset=0&count=100 — returns records 1–100
• Second request: offset=100&count=100 — returns records 101–200
• Continue until the response returns fewer than 100 records

Authentication

Include your API key as a request header or query parameter on all requests:

• Header: api_key: your-api-key-here
• Query parameter: ?api_key=your-api-key-here

Your API key must have the V4 Applications API permission enabled. If you receive a 401 error, ask the key holder to verify this permission is enabled in Settings > API Keys.

Testing

You can explore and test all endpoints interactively using the agentOS Swagger UI at: https://live-api.letmc.com/swagger/ui/index — select "V4.Applications" from the tier dropdown.

Getting help

For technical API support, contact api@agentos.com. For general support with application forms and non-technical queries, contact support@agentos.com.