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

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"
    }],
    "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"
}