Onboarding

Onboard users to the Payr platform with their tenancy details, KYC documents, and optional installment schedules.

User Fields

Field	Type	Required	Description
user_id	integer	Yes	Unique student/tenant reference ID from your system
email	string (email)	Yes	User's email address (used as login identifier, max 254 chars)
first_name	string	Yes	User's first name (max 150 chars)
last_name	string	Yes	User's last name (max 150 chars)
phone_number	string	Yes	Phone number, international format recommended (max 20 chars)
date_of_birth	string (date)	Yes	Format: YYYY-MM-DD
tenant	array	Yes	One or more tenancy objects (see below)
kyc	object	Yes	KYC documents (see below)

Tenant Fields

Field	Type	Required	Description
post_code	string	Yes	Property postal code (max 60 chars)
address_1	string	Yes	Property address line 1 (max 128 chars)
city	string	Yes	Property city (max 60 chars)
country	string	Yes	Property country (max 120 chars)
is_primary	boolean	Yes	Whether this is the user's primary residence
start_rent_date	string (date)	Yes	Tenancy start date (YYYY-MM-DD)
end_rent_date	string (date)	Yes	Tenancy end date (YYYY-MM-DD)
rent_due_day	integer	Yes	Day of month rent is due (1–31)
amount	string (decimal)	Yes	Rental amount, 2 decimal places (e.g., "850.00")
frequency	string (enum)	Yes	Payment frequency (see options below)
is_active	boolean	Yes	Whether the tenancy is currently active
payment_reference	string	Yes	Unique payment reference for this tenancy (max 50 chars)
recipient_bank_sort_code	string	Yes	Landlord's bank sort code (max 50 chars)
recipient_bank_account_number	string	Yes	Landlord's bank account number (max 50 chars)
recipient_bank_account_name	string	Yes	Landlord's bank account name (max 100 chars)
agreement	string (URL)	Yes	URL to the tenancy agreement PDF. Must be publicly accessible — Payr downloads and stores the document.

Frequency options: every_1_month, every_2_month, every_3_month, every_4_month, every_5_month, every_half_year, every_year

Installments Fields

Installments are optional. However, if provided all fields inside installments are required. Documents can be provided at onboarding or later.

Field	Type	Required	Description
installment_number	integer	Yes	increment number document
due_date	Date	Yes	due date for recurring payment document
amount	integer	Yes	amount per payment in pence

KYC Fields

All fields are optional. Documents can be provided at onboarding or later.

Field	Type	Required	Description
pii_front	string (URL) or null	No	URL to the front of the ID document
pii_back	string (URL) or null	No	URL to the back of the ID document
photo	string (URL) or null	No	URL to the user's selfie/photo
status	string	No	KYC status (e.g., "pending", "verified")

Onboard Users

post

https://sandbox-api.mypayr.co.uk/thirdpartyhttps://api.mypayr.co.uk/thirdparty

/onboarding/

Onboard one or more users to the Payr platform with their tenancy details and KYC documents.

If a user already exists (matched by user_id), their information will be updated. If a tenancy already exists (matched by user, start_rent_date, payment_reference, and address_1), only the end_rent_date, amount, and frequency can be updated.

Example cURL Request (Single User)

curl -X POST https://api.mypayr.co.uk/thirdparty/onboarding/ \
  -H "Authorization: Token your_server_token" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 12345,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Smith",
    "phone_number": "[phone]",
    "date_of_birth": "2000-03-15",
    "tenant": [{
      "post_code": "E1 6AN",
      "address_1": "Flat 4, 123 Student Hall",
      "city": "London",
      "country": "United Kingdom",
      "is_primary": true,
      "start_rent_date": "2024-09-01",
      "end_rent_date": "2025-06-30",
      "rent_due_day": 1,
      "amount": "850.00",
      "frequency": "every_1_month",
      "is_active": true,
      "payment_reference": "STU-2024-12345",
      "recipient_bank_sort_code": "20-00-00",
      "recipient_bank_account_number": "55779911",
      "recipient_bank_account_name": "University Housing Ltd",
      "agreement": "https://storage.example.com/agreements/stu_12345.pdf"
    }],
    "installments": [
      {
          "installment_number": 1,
          "due_date": "2026-03-12",
          "amount": 75000 
      },
      {
          "installment_number": 2,
          "due_date": "2026-04-12",
          "amount": 75000
      },
      {
          "installment_number": 3,
          "due_date": "2026-05-12",
          "amount": 75000
      },
      {
          "installment_number": 4,
          "due_date": "2026-06-12",
          "amount": 75000
      }
    ],
    "kyc": {
      "pii_front": "https://storage.example.com/kyc/12345_passport_front.jpg",
      "pii_back": null,
      "photo": "https://storage.example.com/kyc/12345_selfie.jpg",
      "status": "pending"
    }
  }'

Example Response

{
  "message": "Users onboarded successfully"
}

Authorizations

TokenAuth

AuthorizationstringRequired

Server-to-server authentication token obtained via the rotate-token endpoint. Include in the Authorization header as: Authorization: Token <your_token>

Body

application/json

or

Responses

201

Users onboarded successfully

application/json

400

Bad Request - Validation error or processing failure

application/json

401

Unauthorized - Invalid or expired token

application/json

post

/onboarding/

HTTPcURLJavaScriptPython

POST /thirdparty/onboarding/ HTTP/1.1
Host: sandbox-api.mypayr.co.uk
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 840

{
  "user_id": 12345,
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Smith",
  "phone_number": "[phone]",
  "date_of_birth": "2000-03-15",
  "tenant": [
    {
      "post_code": "E1 6AN",
      "address_1": "Flat 4, 123 Student Hall",
      "city": "London",
      "country": "United Kingdom",
      "is_primary": true,
      "start_rent_date": "2024-09-01",
      "end_rent_date": "2025-06-30",
      "rent_due_day": 1,
      "amount": "850.00",
      "frequency": "every_1_month",
      "is_active": true,
      "payment_reference": "STU-2024-12345",
      "recipient_bank_sort_code": "20-00-00",
      "recipient_bank_account_number": "55779911",
      "recipient_bank_account_name": "University Housing Ltd",
      "agreement": "https://storage.example.com/agreements/stu_12345.pdf"
    }
  ],
  "kyc": {
    "pii_front": "https://storage.example.com/kyc/12345_passport_front.jpg",
    "pii_back": null,
    "photo": "https://storage.example.com/kyc/12345_selfie.jpg",
    "status": "pending"
  }
}

Single user with monthly rentSingle user with quarterly rentUser with multiple tenanciesUser with minimal KYC (no documents)Batch onboarding (multiple users)User with half-yearly rent

{
  "message": "Users onboarded successfully"
}