Software auth (/software/auth)

POST

The default REQUEST BODY for software auth to retrieve their access token to use the the Collegia APIs.

Parameter	Type	Description	Required	Inside of
software	JSON object	This object is the default object for request body, inside of it all the necessary information for authentication can be found. The parameters will be described below.	TRUE	-

The software JSON object request body with inner parameters explained in details for software auth to retrieve their access token .

Parameter	Type	Description	Required	Inside of
api_secret	string	Your API secret provided to auth inside the Collegia application to perform operations for your software.	TRUE	software
api_id	string	Your API ID provided to auth inside the Collegia application to perform operations for your software.	TRUE	software

POST

The default REQUEST BODY. to put companies under your software relation. .
Keep in mind that you need to follow the Companies House API - the company_number must be the same.

Parameter	Type	Description	Required	Inside of
`software`	JSON Object	This object is the default object for request body, inside of it all the necessary information to be sent to our services can be found. This is the default request body key identifier. Obs: it's a json object, NOT A JSON ARRAY.	TRUE	-
companies	`array`	This object is the default object for request body, inside of it all the necessary information for authentication can be found. The parameters will be described below.	TRUE	software
admins	`json array`	All the companies need one or more persons to administrate the same (the one(s) to use the Collegia Employers Dashboard). See the add new admin(s) inner section to view all the parameters and parameters-types details before submitting. This is not a optional parameter, need be filled at least one valid admin.	FALSE	companies

The companies JSON object request body with inner parameters explained in details.

Parameter	Type	Description	Required	Inside of
company_number	`string \| integer`	The software number in accordance to the Companies House API. The company number has eight characters, if the input has less than that, zeros will be added to the left of the number for compliance.	TRUE	companies
admins	`array \| json`	You need provide at least a one company admin user. All the admins need the following parameters: `forename` `surname` `email` `password`	TRUE	companies
billing_type	`string`	You need provide the billing type for the company, for now Collegia system only support pull operations for billing operations.	TRUE	companies
primary_email	`string`	You need to provide a company primary email. Warning. Be sure to provide a valid and accessible e-mail, the same will be use by default by Collegia system to provide all the necessary communications with employer, so be sure to provide a valid e-mail. On case of issues or need supporting for change / fix the company e-mail enter in contact with us by e-mail: support@collegia.co.uk.	TRUE	companies
callback_url	`string`	In case of the company has been added on Collegia system wants to use the Collegia UI to complete the setup and wants to be redirect for somewhere in web environment you can provide a `callback_url`, when the setup is over our webview will push you back. Observation: this parameter is mandatory. Disclaimer: all the operation of adding companies is responsibility of the third party software whose is adding it. Collegia is not responsible of wrong operation. Always before to do anything in LIVE \| PRODUCTION environment do an test in our development servers. We strongly suggest to always be 1 week ahead of testing and validating data in our development servers before.	TRUE	companies
terms_accepted	`boolean`	By the default the `terms_accepted` is false value, but can set for true in case the company already read the terms and conditions of use of the Collegia software and auto complete the setup setting up the `paymentInfo` object inside the system. If you set upt the parameter to true you need to provide a valid `paymentInfo` object otherwise the Collegia system will set up an external UI environment for you complete your setup and missing info manually.	FALSE	companies
paymentInfo	`json`	Auto setup employer into our Collegia system, the table bellow will explain all the necessary parameters to be filled to Collegia, remember to fill up a valid `primary_email` for the employer to receive all the Collegia system communications. Always communicate and be sure the company's that you'll add on Collegia system acknowledge before do the operation. Warning: all the process communications needs to have an valid `primary_email` otherwise it'll not be possible to retrieve previously communications, be careful while set up a new employer and assure that employer is already accepted the Collegia terms and use. Collegia is not responsible for the prior communication of inserting any company made by third parties into its software. Always have an open communication with your company(ies) to just add it within our pension system with the consent for it, mainly for the auto setup.	FALSE	companies
setup	`string`	The way you want to setup the new employer, could be `embedded` where the customer can finish all the setup on Collegia UI.	FALSE	companies
is_employer_under_bureau	`boolean`	Identifies if the company is part of a bureau advisor. The default value is false.	FALSE	companies
advisor_email	`string`	Identifies the email of the responsible advisor bureau.	FALSE	companies

The admins JSON object request body with inner parameters explained in details.

Parameter	Type	Description	Required	Inside of
forename	`string (255)`	Name of the admin, need to be valid name with maximum 255 characters.	TRUE	admins
middle_name	`string (255)`	Middle name of the admin,maximum 255 characters.	FALSE	admins
surname	`string (255)`	Surname of the admin, need to be valid name with maximum 255 characters.	TRUE	admins
nickname	`string (255)`	If the person want's to be identified by a nickname.	FALSE	admins
email	`email (255)`	Valid e-mail must be provided for admin(s) can be logged into the Collegia employer dashboard. *Important information:* The admin (just one) `email` can be the same as `primary_email` of company is on the process of adding. Just ONE (and ONLY ONE) can be the same `email` of parent company email (`primary_email` parameter). But we do not encourage this practice since the admin and the company will have they own Collegia e-mail communications. We strongly suggest to each admin use their own company professional e-mail and if in the case the admin doesn't have it use at least a valid e-mail. Disclaimer: the third party software is the responsible for adding the new admin(s) on the Collegia system. In any case of wrong information the third party software IS NOT ALLOWED to edit / erase any information for admin. Once the admin is added on Collegia System the admin as person is the responsible for they own account.	TRUE	admins

POST

The default REQUEST BODY to create contributions for your employees.
Keep in mind that you need to follow the Companies House API – company_number must be the same.

Parameter	Type	Description	Required	Inside of
`papdis`	`JSON ARRAY`	This object is the default object for request body, inside of it all the necessary information for sending data to our services is provided. This is the default request body key identifier.	`TRUE`	-
`employees`	`array`	This object is the default object for request body, inside of it all the necessary information for authentication is provided. The parameters are described next.	`TRUE`	papdis

The JSON object request body with inner parameters explained in detail.

Parameter	Type	Description	Required	Inside of
`company_number`	`string \| integer`	The company number according to the Companies House API.	`TRUE`	papdis
`group`	`string`	Pension sub-identifier. `Alpha Numeric with Symbols String - n/a (will depend on the value assigned by the destination).`	`FALSE`	employees
`subgroup`	`string`	Pension subgroup-identifier. `Alpha Numeric with Symbols String - n/a (will depend on the value assigned by the destination).`	`FALSE`	employees
`payroll_start_date`	`Date string (YYYY-MM-DD)`	The start date of the period in which the payroll is run. NB: You may want to use the pay_reference_start_date, as this is likely to match what has been used in the output Date Null or Valid Date (YYYY-MM-DD) - Cannot be more that 30 days in the future (warning).	`TRUE`	employees
`payroll_end_date`	`Date string (YYYY-MM-DD)`	The end date of the period in which the payroll is ended. As this is likely to match what has been used in the output Date. Valid Date (YYYY-MM-DD).	`TRUE`	employees
`contribution_deduction_date`	`Date string (YYYY-MM-DD)`	The end date of the period in which the payroll is deducted. As this is likely to match what has been used in the output Date . Valid Date (YYYY-MM-DD).	`TRUE`	employees
`frequency_code`	`string`	Frequency of the payroll period covered by the submission Alpha Numeric String. Must be one of: W1 (for weekly) W2 (for fortnightly) TW (for Tax weekly) W4 (for 4 weekly/lunar) M1 (for monthly) TM (for Tax monthly) M3 (for quarterly) M6 (for biannually) MA (for annually)	`TRUE`	employees
`tax_period`	`int`	Tax period of the contribution deduction Number. If Monthly it will be in the range 01 to 12 for a monthly tax schedule, or in the range 01 to 56 (but not 55) for a weekly tax schedule.	`TRUE`	employees
`title`	`string`	The employee title (eg. Mrs., Mr., Dr. and etc...)	`TRUE`	employees
`forename1`	`string`	The employee first name, it's required.	`TRUE`	employees
`forename2`	`string`	The employee middle name is not required, but it is better to add if you have this information.	`FALSE`	employees
`surname`	`string`	The employee last name, it's required.	`TRUE`	employees
`current_gender`	`string`	Current gender, there are 3 possibilities: Non-Binary F (for female) M (for male)	`TRUE`	employees
`employment_start_date`	`Date string (YYYY-MM-DD)`	Date joined employment date. Valid Date (YYYY-MM-DD).	`TRUE`	employees
`exit_date`	`Date string (YYYY-MM-DD) \| NULL`	The date the employee leaves / exits the scheme. Must be used in conjunction with the ExitReasonCode. Must be populated when ExitReasonCode is non null. Where it is populated the following rules apply: Must be greater than or equal to employment_start_date Must be on or before the pay_reference_end_date Must be greater than 16 years and less than or equal to 75 years from birthdate	`FALSE`	employees
`exit_reason_code`	`integer`	The reason for which the employee is no longer a member of the Pension Scheme. NB: should not be used for AE Opt-outs. 1 (Employee left employment) 2 (Ceased active membership, member still employed) 3 (Deceased)	`FALSE`	employees
`assessment_code`	`integer`	An indicator that identifies whether a worker has been assessed or not. If they have been, this gives the outcome of the assessment. Must be used in conjunction with the event_code. See the assessment_code & event_code matrix here. Must be one of: 0 (Excluded) 1 (Eligible Jobholder) 2 (Non-eligible Jobholder) 3 (Entitled Worker) Must be a valid combination with event_code as described in the next section at the foot of this page. Non-enrolled workers If a worker is not an active member of the pension scheme and is not being enrolled in the submission, the assessment_code should be (combined with event_code 0).	`TRUE`	employees
`event_code`	`integer`	An indicator that identifies the action that has occurred. Must be used in conjunction with the assessment_code. See the AssessmentCode & EventCode matrix here. Must be one of: 0 (Not an enrolment event) 1 (Automatic enrolment) 2 (Enrolled) 3 (Voluntary Joiner/Joiner) 4 (Contractual Enrolment) 5 (Opt in/Join request) 6 (Cyclical re-enrolment) 7 (Immediate re-enrolment) Must be a valid combination with assessment_code as described in the next section at the this page.	`TRUE`	employees
`event_date`	`Date (YYYY-MM-DD) \| NULL`	Indicates the date of the action provided in the event_code. Valid Date (YYYY-MM-DD). *Must be populated if event_code is not 0.*. Must be populated if the employee meets one of the following conditions: `assessment_code = 0 and event_code = 4` `assessment_code = 1 and event_code = 1, 2, 3, 6 OR 7` `assessment_code = 2 and event_code = 2, 3 OR 7` `assessment_code = 3 and event_code = 3` `assessment_code = null and event_code = 1, 2, 3 OR 4` If populated then it cannot be more than 5 days in the future compared to the submission date.	`FALSE`	employees
`deferreal_date`	`Date (YYYY-MM-DD) \| NULL`	Day after the Postponement End Date. Must be provided if postponement is being used. Date `NULL` or Valid `Date (YYYY-MM-DD)`	`FALSE`	employees
`ae_opt_out_date`	`Date (YYYY-MM-DD) \| NULL`	This is the Date a valid AE Opt-out notification was received within the AE opt out period. Must not be used for ceased scheme membership while remaining in active service. Date `Null or Valid Date (YYYY-MM-DD)`. If populated: Must be on or after the `event_date` if `event_date` is non `NULL` Must be after the `employment_start_date` Must be before the `pay_reference_end_date`	`FALSE`	employees
`enrolment_communications_issued_date`	`Date (YYYY-MM-DD) \| NULL`	Date on which enrolment communications were issued to confirm that enrolment was achieved. `Date (YYYY-MM-DD) \| NULL`	`FALSE`	employees
`employer_contributions_amount`	`float`	Amount of employer pension contribution in pounds and pence. If contribution made under salary sacrifice, then the total contribution amount should be in this field. `employee_contributions_amount` and `additional_voluntary_contributions_amount` should both be 0.00. `Float -> Up to 2 numbers after the decimal.`	`TRUE`	employees
`employee_contributions_amount`	`float`	Amount of employee pension contribution in pounds and pence. If contribution made under salary sacrifice, then this field be 0.00. Up to 2 digits after the decimal.	`TRUE`	employees
`additional_voluntary_contributions_amount`	`float`	Amount of employee additional voluntary pension contribution in pounds and pence. A zero amount should be entered as 0.00. If contribution made under salary sacrifice, then this field be null or 0.00. Number Up to 2 digits after the decimal.	`FALSE`	employees
`additional_voluntary_contributions_percent`	`float`	The percentage of the employees Additional Voluntary Contributions. Number: Up to 3 digits after the decimal.	`FALSE`	employees
`pensionable_earnings_amount`	`float`	The amount of pensionable pay used to calculate the pension contributions. A zero amount should be entered as 0.00. Number: Up to 2 digits after the decimal. Must be positive or zero.	`FALSE`	employees
`employer_contributions_percent`	`float`	The percentage contributions used to calculate employer contributions. In case of salary sacrifice this field does not need to be affected. It can be either only the employer contributions percent or the sum of employer and employee contributions. `Number: Up to 3 digits after the decimal.`	`FALSE`	employees
`employee_contributions_percent`	`float`	The percentage contributions used to calculate employee contributions. In case of salary sacrifice this field does not need to be affected. It can be either only the employee contributions percent or the sum of employer and employee contributions. `Number: Up to 3 digits after the decimal.`	`FALSE`	employees
`salary_sacrifice_indicator`	`int`	We assume by default that it is not salary sacrifice. 1 - Indicates salary sacrifice. If using salary sacrifice, all contributions should be put under `employer_contributions_amount` and `employee_contributions_amount` should 0. If any value is not provided we'll assume automatically it's `0`.	`FALSE`	employees
`total_gross_qualifying_earnings_amount`	`float`	The (non-banded) earnings used for worker assessment under the automatic enrolment legislation to determine whether the worker is an Eligible Jobholder, Non-Eligible Jobholder or Entitled Worker. A zero amount should be entered as 0.00. Number: up to 2 digits after the decimal.	`FALSE`	employees
`worker_exclusion_code`	`int`	The reason why the Worker is excluded from Assessment. Refer to the Exclusion Code list here. `Integer Must be within the range 0 to 11.`	`FALSE`	employees
`statutory_letter_code`	`string`	Unique identifier representing a unique Letter template to be used by the recipient for Worker communications. Refer to the Statutory Letter Code list here. `Alpha Numeric String Must be one of the codes supported in the Statutory Letter Code list.`	`FALSE`	employees
`is_individual_already_member_of_qps`	`boolean`	Used to indicate if the Worker is already a member of a Qualifying Pension Scheme. `Boolean: true or false`	`FALSE`	employees
`reenrolment_indicator`	`boolean`	Used to indicate whether the worker Assessment can be left until the cyclical re-enrolment date. 'true' indicates that the worker can be left not assessed until cyclical re-enrolment date. BLANK or 'false' indicate the opposite. `Boolean true or false`	`FALSE`	employees
`secondary_email_address`	`string \| null`	A 2nd email address for the Worker. Alpha Numeric with Symbols String Valid Email Address.	`FALSE`	employees
`cyclical_reenrolment_date`	`date (YYYY-MM-DD) \| null`	The date on which all Workers must be assessed for automatic re-enrolment by the Employer. `Date Null or Valid Date (YYYY-MM-DD).`	`FALSE`	employees
`message_function_code`	`int \| null`	Specifies the business function that the sender is requesting. If left BLANK it will be assumed to be 0 (Enrol / Receive Contributions). Must be one of: Null (will be treated as 0) 0 (Enrol / Receive contributions) 1 (Info only) 2 (Assessment request) 3 (Assessment response) 4 (Worker instruction - e.g. Opt out request)	`FALSE`	employees
`pay_reference_start_date`	`date \| null`	Pay Reference Period start date. `Date Null or Valid Date (YYYY-MM-DD)` Must be before the `pay_reference_end_date`. Must match the day that follows the `pay_reference_end_date` of the last successful or partially successful submission.	`FALSE`	employees
`pay_reference_end_date`	`date \| null`	Pay Reference Period end date. `Date Null or Valid Date (YYYY-MM-DD)` Must be after the `pay_reference_start_date`. In conjunction, the PayReferenceStartDate and PayReferenceEndDate, must match the length of the CollectionFrequency for the applicable ContributionGroup of the scheme.	`FALSE`	employees
`opt_out_window_end_date`	`date \| null`	The last day of the one calendar month statutory opt-out window. The Opt-out window does not start until both of the following have occurred: The worker has been enrolled (and active membership achieved). The worker has been given the statutory enrolment letter/email. `Date Null or Valid Date (YYYY-MM-DD)`	`FALSE`	employees
`is_member_an_overseas_national_awaiting_an_nin_number`	`Boolean \| null`	Indicates whether an employee is an overseas national waiting for their National Insurance number to be issued. `Boolean true or false` Must be populated if `national_insurance_number` is not populated If it's not provided it'll be set up to `FALSE` as default.	`FALSE`	employees
`job_title`	`string (70) \| null`	Employee's job title `Alpha Numeric with Symbols String`	`FALSE`	employees
`nationality`	`string \| null`	Employee's nationality `Alpha Numeric with Symbols String`	`FALSE`	employees
`country`	`string (70)`	Employee's country of residence for address purposes `MUST BE IN ISO FORMAT (Examples: GB, BR, PL, IN, UAE)!` *Observation: United Kingdom is `GB` instead* `UK`.**	`TRUE`	employees
`email`	`string`	Employee main address. Note: this is a required attribute since our mailing to the employee will be addressed to this e-mail. Please be extra careful and check that there are no misspellings. DISCLAIMER: you are responsible to ensure that all data provided is accurate. Collegia cannot guarantee a smooth working of the systems under misspelled, wrong, inaccurate or inconsistent information. Before using our production environment, please thoroughly test using our development environment DISCLAIMER: all the email and `PAPDIS` data information is totally employer responsibility, Collegia cannot guarantee the total working progress under misspelled, wrong and inconsistent information. Please be ware for each information that you sent it to us and always (if possible and applicable) try to sent the information to our dev environment before proceed to production.	`TRUE`	employees
`birthdate`	`date (YYYY-MM-DD)`	Employee date of birth.	`TRUE`	employees
`national_insurance_number`	`string`	Employee national insurance number (NIN); this is mandatory in order to process the contributions information of the employee.	`TRUE`	employees
`postal_code`	`string`	Valid country postal code.	`TRUE`	employees
`address1`	`string \| null`	Primary address.	`TRUE`	employees
`address2`	`string \| null`	Secondary address.	`TRUE`	employees
`address3`	`string \| null`	Other address.	`FALSE`	employees
`address4`	`string \| null`	State / Province if applicable.	`FALSE`	employees
`mobile`	`string`	Employee mobile number	`TRUE`	employees
`employee_id`	`string \| null`	In case of the employee still does not have a valid `national_insurance_number` you must provide a unique employee id. Observation: Try to provide an authentic unique employee id. As best practice, please avoid using 1, 2, 4, 5, 6 and etc as `employee_id`. We recommend: Combining the company’s initials with the employee’s initial and 5-numbers sequence (and never repeating the same number sequence), eg: COL-JM-00001. Your next submission must use the same `employee_id`, as the Collegia application will use it to update the employee’s national_insurance_number.	If `national_insurance_number` is null or false the parameter is mandatory (so it's `TRUE`) otherwise `FALSE`.	employees

Appendix

assessment_code	event_code	Description
0 – Excluded	0 – Not an enrolment event	An individual who has not and does not need to be assessed and who is either already a member of a scheme or who is not a member of any scheme.
0 – Excluded	1 – Automatic enrolment / re-enrolment	Not applicable – event_code should be disregarded.
0 – Excluded	2 – Enrolled	Not applicable – event_code should be disregarded.
0 – Excluded	3 – Voluntary Joiner/Joiner	A voluntary joiner who has not and does not need to be assessed (for example, an excluded worker, a company director or a pre-staging company employee).
0 – Excluded	4 – Contractual Enrolment	Either a worker pre-staging or an excluded worker (for example. an overseas resident) who is contractually enrolled.
1 – Eligible Jobholder	0 – Not an enrolment event	An eligible jobholder being contractually enrolled and either: has previously Opted-out or ceased membership, but only needs to be assessed on re-enrolment, or is under a period of postponement.
1 – Eligible Jobholder	1 – Automatic enrolment / re-enrolment	An eligible jobholder being automatically enrolled or re-enrolled.
1 – Eligible Jobholder	2 – Enrolled	An eligible jobholder who has elected to Enrolled to an Automatic Enrolment scheme and either: has previously Opted-out or ceased membership, but only needs to be assessed on re-enrolment, or is under a period of postponement.
1 – Eligible Jobholder	3 – Voluntary Joiner/Joiner	An eligible jobholder who has agreed to join a different level scheme instead of the default automatic enrolment scheme.
1 – Eligible Jobholder	4 – Contractual Enrolment	An eligible jobholder being contractually enrolled and either: has previously Opted-out or ceased membership, but only needs to be assessed on re-enrolment, or is under a period of postponement.
2 – Non-eligible Jobholder	0 – Not an enrolment event	A Non-eligible jobholder, whether in postponement or not, until a future assessment deems them an Eligible Jobholder, an Entitled Worker or an excluded worker. They may or may not already be a member of a pension scheme.
2 – Non-eligible Jobholder	1 – Automatic enrolment / re-enrolment	A Non-eligible jobholder being immediately re-enrolled (for example they are/were a member of a pension scheme which has become non-qualifying and so they are being enrolled into a new AE scheme).
2 – Non-eligible Jobholder	2 – Enrolled	A Non-eligible jobholder who has elected to Enrolled to an Automatic Enrolment scheme, whether in postponement or not.
2 – Non-eligible Jobholder	3 – Voluntary Joiner/Joiner	A Non-eligible jobholder who has elected to join a different level scheme instead of the default automatic enrolment scheme.
2 – Non-eligible Jobholder	4 – Contractual Enrolment	A Non-eligible jobholder being contractually enrolled.
3 – Entitled Worker	0 – Not an enrolment event	An Entitled Worker, until an assessment deems them an Eligible Jobholder, Non-eligible Jobholder or an excluded worker. They may or may not already be a member of a pension scheme.
3 – Entitled Worker	1 – Automatic enrolment / re-enrolment	Not applicable – event_code should be disregarded.
3 – Entitled Worker	2 – Enrolled	Not applicable – event_code should be disregarded. A worker who requests to join or Enrolled, who is then assessed as an Entitled Worker is deemed to have made a request to Join a pension scheme (which does not have to be a qualifying or AE scheme, although the employer is free to allow this if they wish) – and so event_code 3 should be used for this.
3 – Entitled Worker	3 – Voluntary Joiner/Joiner	An Entitled Worker who requests to join a pension scheme (see meaning of Enrolled for an Entitled Worker above).
3 – Entitled Worker	4 – Contractual Enrolment	An Entitled Worker being contractually enrolled.
Blank	0 – Not an enrolment event	An individual who is either already a member of a scheme or who is not a member of any scheme – where no worker category has been provided or is unknown.
Blank	1 – Automatic enrolment / re-enrolment	An eligible jobholder being automatically enrolled/re-enrolled or a Non-eligible jobholder being immediately re- enrolled.
Blank	2 – Enrolled	A jobholder (eligible or non-eligible) who has elected to Enrolled to an Automatic Enrolment scheme, whether in postponement or not.
Blank	3 – Voluntary Joiner/Joiner	A voluntary joiner of unknown worker category.
Blank	4 – Contractual Enrolment	An individual of unknown worker category being contractually enrolled.