> For the complete documentation index, see [llms.txt](https://docs.payr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payr.com/onboarding.md). # 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 user/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. | | `installment_payment` | object | No | Optional installment payment schedule (see below) | **Frequency options:** `every_1_month`, `every_2_month`, `every_3_month`, `every_4_month`, `every_5_month`, `every_half_year`, `every_year` **Installment Payment Fields (Optional - nested in tenant)** For recurring payments, you can include an installment payment schedule within each tenant object. All fields are optional. | Field | Type | Required | Description | | -------------- | ------ | -------- | --------------------------------------------------- | | `total_amount` | number | No | Total amount for the full tenancy period | | `installments` | array | No | Array of individual installment objects (see below) | **Installment Object Fields:** | Field | Type | Required | Description | | -------------------- | ------------- | -------- | --------------------------------------------- | | `installment_number` | integer | Yes | Sequential installment number (e.g., 1, 2, 3) | | `due_date` | string (date) | Yes | Due date for this installment (`YYYY-MM-DD`) | | `amount` | number | Yes | Amount due for this installment | #### 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 > 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)\ > \`\`\`bash\ > curl -X POST \\\ > -H "Authorization: Token your\_server\_token" \\\ > -H "Content-Type: application/json" \\\ > -d '{\ > "user\_id": 12345,\ > "email": "",\ > "first\_name": "John",\ > "last\_name": "Smith",\ > "phone\_number": "+447900123456",\ > "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": " > }],\ > "kyc": {\ > "pii\_front": " > "pii\_back": null,\ > "photo": " > "status": "pending"\ > }\ > }'\ > \`\`\`\ > \ > \### Example Response\ > \`\`\`json\ > {\ > "message": "Users onboarded successfully"\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Payr Integration API","version":"1.0.0"},"tags":[{"name":"Onboarding","description":"Onboard users to the Payr platform with their tenancy details, KYC documents, and optional installment schedules.\n\n### User Fields\n\n| Field | Type | Required | Description |\n| ----- | ---- | -------- | ----------- |\n| `user_id` | integer | Yes | Unique user/tenant reference ID from your system |\n| `email` | string (email) | Yes | User's email address (used as login identifier, max 254 chars) |\n| `first_name` | string | Yes | User's first name (max 150 chars) |\n| `last_name` | string | Yes | User's last name (max 150 chars) |\n| `phone_number` | string | Yes | Phone number, international format recommended (max 20 chars) |\n| `date_of_birth` | string (date) | Yes | Format: `YYYY-MM-DD` |\n| `tenant` | array | Yes | One or more tenancy objects (see below) |\n| `kyc` | object | Yes | KYC documents (see below) |\n\n### Tenant Fields\n\n| Field | Type | Required | Description |\n| ----- | ---- | -------- | ----------- |\n| `post_code` | string | Yes | Property postal code (max 60 chars) |\n| `address_1` | string | Yes | Property address line 1 (max 128 chars) |\n| `city` | string | Yes | Property city (max 60 chars) |\n| `country` | string | Yes | Property country (max 120 chars) |\n| `is_primary` | boolean | Yes | Whether this is the user's primary residence |\n| `start_rent_date` | string (date) | Yes | Tenancy start date (`YYYY-MM-DD`) |\n| `end_rent_date` | string (date) | Yes | Tenancy end date (`YYYY-MM-DD`) |\n| `rent_due_day` | integer | Yes | Day of month rent is due (1–31) |\n| `amount` | string (decimal) | Yes | Rental amount, 2 decimal places (e.g., `\"850.00\"`) |\n| `frequency` | string (enum) | Yes | Payment frequency (see options below) |\n| `is_active` | boolean | Yes | Whether the tenancy is currently active |\n| `payment_reference` | string | Yes | Unique payment reference for this tenancy (max 50 chars) |\n| `recipient_bank_sort_code` | string | Yes | Landlord's bank sort code (max 50 chars) |\n| `recipient_bank_account_number` | string | Yes | Landlord's bank account number (max 50 chars) |\n| `recipient_bank_account_name` | string | Yes | Landlord's bank account name (max 100 chars) |\n| `agreement` | string (URL) | Yes | URL to the tenancy agreement PDF. **Must be publicly accessible** — Payr downloads and stores the document. |\n| `installment_payment` | object | No | Optional installment payment schedule (see below) |\n\n**Frequency options:** `every_1_month`, `every_2_month`, `every_3_month`, `every_4_month`, `every_5_month`, `every_half_year`, `every_year`\n\n#### Installment Payment Fields (Optional - nested in tenant)\n\nFor recurring payments, you can include an installment payment schedule within each tenant object. All fields are optional.\n\n| Field | Type | Required | Description |\n| ----- | ---- | -------- | ----------- |\n| `total_amount` | number | No | Total amount for the full tenancy period |\n| `installments` | array | No | Array of individual installment objects (see below) |\n\n**Installment Object Fields:**\n\n| Field | Type | Required | Description |\n| ----- | ---- | -------- | ----------- |\n| `installment_number` | integer | Yes | Sequential installment number (e.g., 1, 2, 3) |\n| `due_date` | string (date) | Yes | Due date for this installment (`YYYY-MM-DD`) |\n| `amount` | number | Yes | Amount due for this installment |\n\n### KYC Fields\n\nAll fields are optional. Documents can be provided at onboarding or later.\n\n| Field | Type | Required | Description |\n| ----- | ---- | -------- | ----------- |\n| `pii_front` | string (URL) or null | No | URL to the front of the ID document |\n| `pii_back` | string (URL) or null | No | URL to the back of the ID document |\n| `photo` | string (URL) or null | No | URL to the user's selfie/photo |\n| `status` | string | No | KYC status (e.g., `\"pending\"`, `\"verified\"`) |\n"}],"servers":[{"url":"https://sandbox-api.mypayr.co.uk/thirdparty","description":"Sandbox server"},{"url":"https://api.mypayr.co.uk/thirdparty","description":"Production server"}],"security":[{"TokenAuth":[]}],"components":{"securitySchemes":{"TokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Server-to-server authentication token obtained via the rotate-token endpoint.\nInclude in the Authorization header as: `Authorization: Token `\n"}},"schemas":{"UserOnboardingRequest":{"type":"object","required":["user_id","email","first_name","last_name","phone_number","date_of_birth","tenant","kyc"],"properties":{"user_id":{"type":"integer","description":"Unique user/tenant reference ID from the external system"},"email":{"type":"string","format":"email","maxLength":254,"description":"User's email address"},"first_name":{"type":"string","maxLength":150,"description":"User's first name"},"last_name":{"type":"string","maxLength":150,"description":"User's last name"},"phone_number":{"type":"string","maxLength":20,"description":"User's phone number (international format recommended)"},"date_of_birth":{"type":"string","format":"date","description":"User's date of birth (YYYY-MM-DD)"},"tenant":{"type":"array","items":{"$ref":"#/components/schemas/TenantDetails"},"description":"List of tenancy/rental properties for the user","minItems":1},"kyc":{"$ref":"#/components/schemas/KYCDetails"}}},"TenantDetails":{"type":"object","required":["post_code","address_1","city","country","is_primary","start_rent_date","end_rent_date","rent_due_day","amount","frequency","is_active","payment_reference","recipient_bank_sort_code","recipient_bank_account_number","recipient_bank_account_name","agreement"],"properties":{"post_code":{"type":"string","maxLength":60,"description":"Property postal code"},"address_1":{"type":"string","maxLength":128,"description":"Property address line 1"},"city":{"type":"string","maxLength":60,"description":"Property city"},"country":{"type":"string","maxLength":120,"description":"Property country"},"is_primary":{"type":"boolean","description":"Whether this is the primary residence"},"start_rent_date":{"type":"string","format":"date","description":"Tenancy start date (YYYY-MM-DD)"},"end_rent_date":{"type":"string","format":"date","description":"Tenancy end date (YYYY-MM-DD)"},"rent_due_day":{"type":"integer","minimum":1,"maximum":31,"description":"Day of the month when rent is due"},"amount":{"type":"string","format":"decimal","description":"Rental amount (up to 10 digits, 2 decimal places)"},"frequency":{"type":"string","enum":["every_1_month","every_2_month","every_3_month","every_4_month","every_5_month","every_half_year","every_year"],"description":"Rent payment frequency"},"is_active":{"type":"boolean","description":"Whether the tenancy is currently active"},"payment_reference":{"type":"string","maxLength":50,"description":"Unique payment reference for this tenancy"},"recipient_bank_sort_code":{"type":"string","maxLength":50,"description":"Landlord's bank sort code"},"recipient_bank_account_number":{"type":"string","maxLength":50,"description":"Landlord's bank account number"},"recipient_bank_account_name":{"type":"string","maxLength":100,"description":"Landlord's bank account name"},"agreement":{"type":"string","format":"uri","description":"URL to the tenancy agreement document (PDF)"},"installment_payment":{"$ref":"#/components/schemas/InstallmentPayment","description":"Optional installment payment schedule for this tenancy"}}},"InstallmentPayment":{"type":"object","properties":{"total_amount":{"type":"number","description":"Total amount for the full tenancy period"},"installments":{"type":"array","items":{"$ref":"#/components/schemas/Installment"},"description":"Array of individual installment objects"}}},"Installment":{"type":"object","required":["installment_number","due_date","amount"],"properties":{"installment_number":{"type":"integer","description":"Sequential installment number"},"due_date":{"type":"string","format":"date","description":"Due date for this installment (YYYY-MM-DD)"},"amount":{"type":"number","description":"Amount due for this installment"}}},"KYCDetails":{"type":"object","properties":{"pii_front":{"type":"string","format":"uri","nullable":true,"description":"URL to the front of the ID document"},"pii_back":{"type":"string","format":"uri","nullable":true,"description":"URL to the back of the ID document"},"photo":{"type":"string","format":"uri","nullable":true,"description":"URL to the user's photo/selfie"},"status":{"type":"string","description":"KYC status (optional)"}}},"OnboardingSuccessResponse":{"type":"object","properties":{"message":{"type":"string","description":"Success message"}}},"ValidationErrorResponse":{"type":"object","additionalProperties":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"string"}]}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"detail":{"type":"string","description":"Detailed error information"}}}}},"paths":{"/onboarding/":{"post":{"summary":"Onboard Users","description":"Onboard one or more users to the Payr platform with their tenancy details and KYC documents.\n\nIf a user already exists (matched by `user_id`), their information will be updated.\nIf 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.\n\n### Example cURL Request (Single User)\n```bash\ncurl -X POST https://api.mypayr.co.uk/thirdparty/onboarding/ \\\n -H \"Authorization: Token your_server_token\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"user_id\": 12345,\n \"email\": \"john.smith@university.edu\",\n \"first_name\": \"John\",\n \"last_name\": \"Smith\",\n \"phone_number\": \"+447900123456\",\n \"date_of_birth\": \"2000-03-15\",\n \"tenant\": [{\n \"post_code\": \"E1 6AN\",\n \"address_1\": \"Flat 4, 123 Student Hall\",\n \"city\": \"London\",\n \"country\": \"United Kingdom\",\n \"is_primary\": true,\n \"start_rent_date\": \"2024-09-01\",\n \"end_rent_date\": \"2025-06-30\",\n \"rent_due_day\": 1,\n \"amount\": \"850.00\",\n \"frequency\": \"every_1_month\",\n \"is_active\": true,\n \"payment_reference\": \"STU-2024-12345\",\n \"recipient_bank_sort_code\": \"20-00-00\",\n \"recipient_bank_account_number\": \"55779911\",\n \"recipient_bank_account_name\": \"University Housing Ltd\",\n \"agreement\": \"https://storage.example.com/agreements/stu_12345.pdf\"\n }],\n \"kyc\": {\n \"pii_front\": \"https://storage.example.com/kyc/12345_passport_front.jpg\",\n \"pii_back\": null,\n \"photo\": \"https://storage.example.com/kyc/12345_selfie.jpg\",\n \"status\": \"pending\"\n }\n }'\n```\n\n### Example Response\n```json\n{\n \"message\": \"Users onboarded successfully\"\n}\n```\n","operationId":"onboardUsers","tags":["Onboarding"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UserOnboardingRequest"},{"type":"array","items":{"$ref":"#/components/schemas/UserOnboardingRequest"}}]}}}},"responses":{"201":{"description":"Users onboarded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingSuccessResponse"}}}},"400":{"description":"Bad Request - Validation error or processing failure","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/ErrorResponse"}]}}}},"401":{"description":"Unauthorized - Invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ````