API for untied STAR (Secure tax authorisation and reporting) service.
\nAn API key is required. Contact untied for access.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"7541671","collectionId":"9b43d00b-d3f7-4b0d-8548-96788ebad0a2","publishedId":"2s946bDap8","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2023-07-11T11:04:30.000Z"},"item":[{"name":"Endpoints","item":[{"name":"invite","id":"b67d9558-0df8-491e-b202-3a6fd13828f6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-api-key","value":"960528cd-7718-4b2b-b192-648e3da56dd7","type":"text"}],"body":{"mode":"raw","raw":"{\n \"batch_email\": \"marcus@untied.io\",\n \"batch_ref\": \"MJT12ABC001\",\n \"send_invite_emails\": \"Y\",\n \"taxpayers\": [\n {\"nino\": \"QQ000001A\", \"dob\": \"1970-01-03\", \"email\": \"user1@somewhere.com\", \"ref\": \"\"},\n {\"nino\": \"QQ000001B\", \"dob\": \"2006-06-21\", \"email\": \"user2@somewhere.com\", \"ref\": \"\"}\n ],\n \"webhook_url\": \"https://someplace.com/webhook\"\n}","options":{"raw":{"language":"json"}}},"url":"https://star-client-api.untied.io/invite","description":"Create invite batch. Use this to invite taxpayers to give you access to their income records.
\nIf send_invite_emails is set to \"Y\" an email will be sent to each taxpayer containing their HMRC invite link that they will need to click on in order to authorise access to their data.
\nThe invite email template and other settings can be configured in your dashboard at https://asr.untied.io/
\nBody parameters:
\ntaxpayers: array of taxpayers to invite
\nbatch_email: where to send the batch processing report
\nbatch_ref: optional - if omitted a GUID will be created
\nsend_invite_emails: optional - default is \"N\". If \"Y\" invite links will be sent to taxpayers
\nwebhook_url: webhook url which is POSTed to with updates. See below.
\nsynchronous: optional. Default: \"N\". If \"Y\" and only if taxpayers has only ONE item the invite for that taxpayer will be processed synchronously before the endpoint returns (this can take ~10 seconds).
\nauto_update: optional. Default: \"Y\". If set to \"N\" a data update will not take place on invite acceptance.
\nNote that if a taxpayer in this batch has already been invited on a different batch, but has not accepted, the taxpayer will be moved to this new batch so that the invite will be renewed. Invites are valid for 21 days. Therefore if the taxpayer does not accept within that time a new invite will need to be generated. This can be done by creating a new batch with the same taxpayer details.
\nWebhook payloads
\nInvite complete. When the batch of invites has been processed. Check the batch with GET /batch/ to find the status of each taxpayer's invite.
\n{\n \"batch_id\": <batch_id>,\n \"type\": \"invite\",\n \"status\": \"complete\"\n}\n\nIf any taxpayers in the batch exist in your account and have accepted an invite already you will see something like the following:
\n{\n \"batch_id\": <batch_id>,\n \"taxpayers_already_registered\": [\n {\n \"id\": 196,\n \"nino\": \"NX112233A\"\n }\n ],\n \"type\": \"invite\",\n \"status\": \"complete\"\n}\n\nIf all the taxpayers passed are already registered there is nothing to do and therefore the webhook will not fire.
\nInvite accepted. When a user has accepted an invite:
\n{\n \"batch_id\": <batch_id>,\n \"taxpayer_id\": <taxpayer_id>,\n \"type\": \"invite_accepted\",\n \"status\": \"complete\"\n}\n\nData update. As long as auto_update is not \"N\" data will be requested as soon as the client accepts the invite.
\nJSON
\n{\n \"taxpayer_id\": <taxpayer_id>, \n \"type\": \"data_update\",\n \"status\": \"complete\"\n}\n\nIf the taxpayer actively declines the invite, \"invite_declined\" will be sent to the webhook:
\n{\n \"batch_id\": <batch_id>,\n \"taxpayer_id\": <taxpayer_id>,\n \"type\": \"invite_declined\",\n \"status\": \"complete\"\n}\n\nList invite batches.
\n","urlObject":{"path":["batches"],"host":["https://star-client-api.untied.io"],"query":[],"variable":[]}},"response":[{"id":"70c94589-52e4-4bc7-a0ec-92ea885f9c44","name":"invite batches example","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"960528cd-7718-4b2b-b192-648e3da56dd7","type":"text"}],"url":"https://star-client-api.untied.io/batches"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"content-type","value":"application/json"},{"key":"X-Cloud-Trace-Context","value":"cee24bd6e77375e70f06306367f0646c"},{"key":"Date","value":"Tue, 11 Jul 2023 10:32:16 GMT"},{"key":"Server","value":"Google Frontend"},{"key":"Content-Length","value":"1172"},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000"}],"cookie":[],"responseTime":null,"body":"{\n \"batches\": [\n {\n \"batch_email\": \"tin.demo@untied.io\",\n \"batch_ref\": \"6413544d162a4\",\n \"id\": 25,\n \"send_invite_emails\": \"N\"\n },\n {\n \"batch_email\": \"support@untied.io\",\n \"batch_ref\": \"Batch today\",\n \"id\": 26,\n \"send_invite_emails\": \"N\"\n },\n {\n \"batch_email\": \"support@untied.io\",\n \"batch_ref\": \"645392eaa07b4\",\n \"id\": 33,\n \"send_invite_emails\": \"N\"\n },\n {\n \"batch_email\": \"tin.demo@untied.io\",\n \"batch_ref\": \"645a0cff07f3f\",\n \"id\": 34,\n \"send_invite_emails\": \"N\"\n },\n {\n \"batch_email\": \"support@untied.io\",\n \"batch_ref\": \"645e441eab959\",\n \"id\": 35,\n \"send_invite_emails\": \"N\"\n },\n {\n \"batch_email\": \"support@untied.io\",\n \"batch_ref\": \"646f6fbe3dc1a\",\n \"id\": 38,\n \"send_invite_emails\": \"N\"\n },\n {\n \"batch_email\": \"support@untied.io\",\n \"batch_ref\": \"64773d967c075\",\n \"id\": 40,\n \"send_invite_emails\": \"N\"\n },\n {\n \"batch_email\": \"support@untied.io\",\n \"batch_ref\": \"6479a5da29405\",\n \"id\": 41,\n \"send_invite_emails\": \"N\"\n },\n {\n \"batch_email\": \"support@untied.io\",\n \"batch_ref\": \"6479aa38aca14\",\n \"id\": 42,\n \"send_invite_emails\": \"N\"\n },\n {\n \"batch_email\": \"support@untied.io\",\n \"batch_ref\": \"ABC1\",\n \"id\": 43,\n \"send_invite_emails\": \"Y\"\n },\n {\n \"batch_email\": \"support@untied.io\",\n \"batch_ref\": \"TT1\",\n \"id\": 44,\n \"send_invite_emails\": \"Y\"\n },\n {\n \"batch_email\": \"marcus@untied.io\",\n \"batch_ref\": \"MJT12ABC\",\n \"id\": 54,\n \"send_invite_emails\": \"Y\"\n }\n ],\n \"status\": \"success\"\n}"}],"_postman_id":"97d338cc-b8e1-4f38-a38d-3903a6fc7756"},{"name":"Get invite batch","id":"15fc9510-160f-4d5f-bf8c-8c27f3e55a9e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-api-key","value":"960528cd-7718-4b2b-b192-648e3da56dd7","type":"text"}],"url":"https://star-client-api.untied.io/batch/54","description":"Retrieve a specific batch including all invited taxpayers and their status.
\nThe response includes an array of taxpayers invited in the batch. Each taxpayer object will include an invite_url that the client should be sent to to authorise untied to view their records.
\nIf a taxpayer is already registered with untied the invite_url will be empty, registered will be \"Y\" and the message will be \"Taxpayer already registered\". In this case data can be requested immediately and there is no need to ask the taxpayer to authorise.
\nIf an error occurred when creating an invite 'error' will be 'Y' and the error message will be in the 'message' attribute. Possible errors include:
\n\"Service unavailable\" - an error occurred trying to access HMRC's invite service
\n\"Service error\" - an error was reported by HMRC when trying to invite the user. This could be an issue with the taxpayer itself or an issue with HMRC.
\n\"NINO error\"
\n\"NINO and DOB do not match\"
\nIf the invite process has not yet completed or if there is an error, invite_url will be null and found will be \"N\".
\nWhile it is possible to poll /batch and check these values it is more efficient to specify a webhook on the /invite.
\n","urlObject":{"path":["batch","54"],"host":["https://star-client-api.untied.io"],"query":[],"variable":[]}},"response":[{"id":"bb03929c-714d-499f-95f7-793ebb6c6a78","name":"get invite batch example","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"960528cd-7718-4b2b-b192-648e3da56dd7","type":"text"}],"url":"https://star-client-api.untied.io/batch/54"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"Werkzeug/2.3.4 Python/3.11.3"},{"key":"Date","value":"Tue, 11 Jul 2023 10:14:07 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"666"},{"key":"Connection","value":"close"}],"cookie":[],"responseTime":null,"body":"{\n \"batch\": {\n \"batch_email\": \"sssss@xxxaaa.io\",\n \"batch_ref\": \"MJT12ABC\",\n \"id\": 54,\n \"send_invite_emails\": \"Y\"\n },\n \"taxpayers\": [\n {\n \"custom_ref\": \"MJT12ABC\",\n \"dob\": \"Wed, 20 Feb 1980 00:00:00 GMT\",\n \"email\": \"user1@somewhere.com\",\n \"error\": \"Y\",\n \"found\": \"N\",\n \"id\": 111,\n \"invite_url\": \"https://star-client-api.untied.io/authLink/87b50ee8-2e26-4e92-b633-5ff66795439c\",\n \"message\": \"NINO and DOB do not match\", \n \"nino\": \"NX112233B\",\n \"processed\": \"Y\",\n \"registered\": \"N\",\n \"requested\": \"Tue, 11 Jul 2023 09:43:24 GMT\"\n },\n {\n \"custom_ref\": \"MJT12ABC\",\n \"dob\": \"Tue, 20 Feb 1990 00:00:00 GMT\",\n \"email\": \"user2@somewhere.com\",\n \"error\": \"Y\", \n \"found\": \"N\",\n \"id\": 112,\n \"invite_url\": \"https://star-client-api.untied.io/authLink/87b50ee8-2e26-4e92-b633-5ff66795439c\",\n \"message\": \"NINO and DOB do not match\",\n \"nino\": \"NX112233C\",\n \"processed\": \"Y\",\n \"registered\": \"N\",\n \"requested\": \"Tue, 11 Jul 2023 09:43:24 GMT\"\n }\n ],\n \"status\": \"success\"\n}"}],"_postman_id":"15fc9510-160f-4d5f-bf8c-8c27f3e55a9e"},{"name":"List taxpayers","id":"5b5fb8a1-0b2f-4cac-aac9-c9bdfd98c0e2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"x-api-key","value":"960528cd-7718-4b2b-b192-648e3da56dd7","type":"text"}],"url":"https://star-client-api.untied.io/taxpayers","description":"List all taxpayers that have completed invite processing successfully. Registration status is checked daily.
\nTo view status of recently invited taxpayers or to see ones that have failed use the get batch endpoint.
\n","urlObject":{"path":["taxpayers"],"host":["https://star-client-api.untied.io"],"query":[],"variable":[]}},"response":[{"id":"cea43ce0-9fbb-48b7-abd3-7399854276ec","name":"List taxpayers","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"960528cd-7718-4b2b-b192-648e3da56dd7","type":"text"}],"url":"https://star-client-api.untied.io/taxpayers"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"content-type","value":"application/json"},{"key":"X-Cloud-Trace-Context","value":"64eb4cd36fc49c968ccf95808ee09497;o=1"},{"key":"Date","value":"Tue, 11 Jul 2023 10:49:08 GMT"},{"key":"Server","value":"Google Frontend"},{"key":"Content-Length","value":"781"},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"date_processed\": \"Mon, 10 Jul 2023 13:00:16 GMT\",\n \"dob\": \"Wed, 24 Jan 1973 00:00:00 GMT\",\n \"email\": \"mike@somedomain.com\",\n \"id\": 74,\n \"last_updated\": \"Wed, 17 May 2023 11:20:17 GMT\",\n \"name\": \"Michael Smith\",\n \"nino\": \"NX998877C\",\n \"processed\": \"Y\",\n \"reference\": \"MS01\",\n \"registered\": \"Y\"\n },\n {\n \"date_processed\": \"Mon, 10 Jul 2023 14:00:29 GMT\",\n \"dob\": \"Sat, 25 Oct 1975 00:00:00 GMT\",\n \"email\": \"hello@mail.com\",\n \"id\": 103,\n \"last_updated\": null,\n \"name\": \"Susanne Price\",\n \"nino\": \"JE987651A\",\n \"processed\": \"Y\",\n \"reference\": \"MJT02\",\n \"registered\": \"Y\"\n },\n {\n \"date_processed\": \"Mon, 10 Jul 2023 14:00:19 GMT\",\n \"dob\": \"Sun, 22 Aug 1971 00:00:00 GMT\",\n \"email\": \"demo@place.com\",\n \"id\": 100,\n \"last_updated\": null,\n \"name\": \"KEITH SOPER\",\n \"nino\": \"NX003320A\",\n \"processed\": \"Y\",\n \"reference\": \"Ref1\",\n \"registered\": \"Y\"\n }\n ],\n \"status\": \"success\"\n}"}],"_postman_id":"5b5fb8a1-0b2f-4cac-aac9-c9bdfd98c0e2"},{"name":"Get taxpayer","id":"e6f3b8b2-0b5a-41be-8813-5071b912f762","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"x-api-key","value":"960528cd-7718-4b2b-b192-648e3da56dd7","type":"text"}],"url":"https://star-client-api.untied.io/taxpayer/188","description":"Retrieve specific taxpayer using the id returned in List taxpayers. This also retrieves financial data.
\nIf the taxpayer is registered (has accepted an invite) financial data is updated as follows:
\nImmediately after the taxpayer has accepted their invite (unless auto_update is 'N' on the invite request)
\nOnce per day
\nBy calling the updateTaxpayer endpoint
\nDuring update the status is checked. If the taxpayer has revoked authorisation it will show as cancelled.
\nNote that the type of data retrieved depends on the scope of your account. The example here shows all possible attibutes.
\n","urlObject":{"path":["taxpayer","188"],"host":["https://star-client-api.untied.io"],"query":[],"variable":[]}},"response":[{"id":"9a11c3be-8155-4779-846f-d3545e857a11","name":"Get taxpayer","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"960528cd-7718-4b2b-b192-648e3da56dd7","type":"text"}],"url":"https://star-client-api.untied.io/taxpayer/74"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"content-type","value":"application/json"},{"key":"X-Cloud-Trace-Context","value":"167ea8042f80eca3c0a1c8e4a47a45d3;o=1"},{"key":"Date","value":"Tue, 11 Jul 2023 10:32:12 GMT"},{"key":"Server","value":"Google Frontend"},{"key":"Content-Length","value":"6427"},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000"}],"cookie":[],"responseTime":null,"body":"{\n \"allowances\": [],\n \"debts\": [\n {\n \"id\": 954,\n \"name\": \"Underpaid tax for earlier years included in tax code for 2022 to 2023 Also shown as 'amount of underpaid tax for earlier years' on a client's P2, 'PAYE Coding Notice'. \",\n \"tax_year\": \"2022-2023\",\n \"updated\": \"Thu, 25 May 2023 13:00:26 GMT\",\n \"value\": \"£0.00\"\n },\n {\n \"id\": 955,\n \"name\": \"Underpaid tax for 2022 to 2023 included in tax code for 2023 to 2024 Also shown as 'estimated underpayment for 2022 to 2023' on a client's P2, 'PAYE Coding Notice'. \",\n \"tax_year\": \"2022-2023\",\n \"updated\": \"Thu, 25 May 2023 13:00:26 GMT\",\n \"value\": \"£0.00\"\n },\n {\n \"id\": 956,\n \"name\": \"Outstanding debt included in tax code for 2022 to 2023 Debts may relate to Self Assessment, tax credits or National Insurance Class 2.\",\n \"tax_year\": \"2022-2023\",\n \"updated\": \"Thu, 25 May 2023 13:00:26 GMT\",\n \"value\": \"£0.00\"\n },\n {\n \"id\": 2169,\n \"name\": \"Underpaid tax for earlier years included in tax code for 2022 to 2023 Also shown as 'amount of underpaid tax for earlier years' on a client's P2, 'PAYE Coding Notice'. \",\n \"tax_year\": \"2022-2023\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:22 GMT\",\n \"value\": \"£0.00\"\n },\n {\n \"id\": 2170,\n \"name\": \"Underpaid tax for 2022 to 2023 included in tax code for 2023 to 2024 Also shown as 'estimated underpayment for 2022 to 2023' on a client's P2, 'PAYE Coding Notice'. \",\n \"tax_year\": \"2022-2023\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:22 GMT\",\n \"value\": \"£0.00\"\n },\n {\n \"id\": 2171,\n \"name\": \"Outstanding debt included in tax code for 2022 to 2023 Debts may relate to Self Assessment, tax credits or National Insurance Class 2.\",\n \"tax_year\": \"2022-2023\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:22 GMT\",\n \"value\": \"£0.00\"\n }\n ],\n \"employments\": [\n {\n \"allowances\": {\n \"Gift aid payments\": \"£385\",\n \"Personal allowance\": \"£0\"\n },\n \"benefits\": {},\n \"deductions\": {\n \"Adjustment to rate band\": {\n \"deducted\": \"£63,307\",\n \"owed\": \"£0\"\n },\n \"Car benefit\": {\n \"deducted\": \"£996\",\n \"owed\": \"\"\n }\n },\n \"end_date\": \"Ongoing\",\n \"id\": 7916,\n \"name\": \"ACME ONE LTD\",\n \"paye_ref\": \"504/2609\",\n \"start_date\": \"6 Apr 2017\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"K6390X\",\n \"tax_paid\": \"£51\",\n \"tax_year\": \"2023-2024\",\n \"taxable_income\": \"£3,150\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:18 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7917,\n \"name\": \"COMPANY TWO LTD\",\n \"paye_ref\": \"120/EE01587\",\n \"start_date\": \"6 Mar 2020\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"D1X\",\n \"tax_paid\": \"£250\",\n \"tax_year\": \"2023-2024\",\n \"taxable_income\": \"£1,250\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:19 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7918,\n \"name\": \"COMPANY THREE LTD\",\n \"paye_ref\": \"120/KE46334\",\n \"start_date\": \"6 Apr 2022\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"BR\",\n \"tax_paid\": \"£6,180\",\n \"tax_year\": \"2023-2024\",\n \"taxable_income\": \"£30,900\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:19 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7919,\n \"name\": \"ACME ONE LTD\",\n \"paye_ref\": \"504/2609\",\n \"start_date\": \"6 Apr 2017\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£406.20\",\n \"tax_year\": \"2022-2023\",\n \"taxable_income\": \"£11,920.50\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:21 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7920,\n \"name\": \"COMPANY TWO LTD\",\n \"paye_ref\": \"120/EE01587\",\n \"start_date\": \"6 Mar 2020\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£993.40\",\n \"tax_year\": \"2022-2023\",\n \"taxable_income\": \"£6,666.66\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:21 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7921,\n \"name\": \"COMPANY THREE LTD\",\n \"paye_ref\": \"120/KE46334\",\n \"start_date\": \"6 Apr 2022\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£1,120\",\n \"tax_year\": \"2022-2023\",\n \"taxable_income\": \"£5,600\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:22 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7924,\n \"name\": \"ACME ONE LTD\",\n \"paye_ref\": \"504/2609\",\n \"start_date\": \"6 Apr 2017\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£4,072.10\",\n \"tax_year\": \"2021-2022\",\n \"taxable_income\": \"£9,564\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:24 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7926,\n \"name\": \"COMPANY TWO LTD\",\n \"paye_ref\": \"120/EE01587\",\n \"start_date\": \"6 Mar 2020\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£16,000\",\n \"tax_year\": \"2021-2022\",\n \"taxable_income\": \"£80,000.04\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:24 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7930,\n \"name\": \"COMPANY TWO LTD\",\n \"paye_ref\": \"504/2609\",\n \"start_date\": \"6 Apr 2017\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£144\",\n \"tax_year\": \"2020-2021\",\n \"taxable_income\": \"£8,712\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:26 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7932,\n \"name\": \"ACME ONE LTD\",\n \"paye_ref\": \"120/EE01587\",\n \"start_date\": \"6 Mar 2020\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£10,582.80\",\n \"tax_year\": \"2020-2021\",\n \"taxable_income\": \"£46,666.69\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:26 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7938,\n \"name\": \"COMPANY TWO LTD\",\n \"paye_ref\": \"504/2609\",\n \"start_date\": \"6 Apr 2017\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£151.60\",\n \"tax_year\": \"2019-2020\",\n \"taxable_income\": \"£8,628\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:28 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7940,\n \"name\": \"ACME ONE LTD\",\n \"paye_ref\": \"120/EE01587\",\n \"start_date\": \"6 Mar 2020\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£0\",\n \"tax_year\": \"2019-2020\",\n \"taxable_income\": \"£0\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:28 GMT\"\n }\n ],\n \"statePensions\": [],\n \"status\": \"success\",\n \"taxpayerInfo\": [\n {\n \"date_processed\": \"Mon, 10 Jul 2023 13:00:16 GMT\",\n \"dob\": \"Wed, 26 Jan 1972 00:00:00 GMT\",\n \"email\": \"fred@blogs.ai\",\n \"id\": 74,\n \"last_updated\": \"Wed, 17 May 2023 11:20:17 GMT\",\n \"name\": \"Fred Bloggs\",\n \"nino\": \"XX998877Z\",\n \"processed\": \"Y\",\n \"reference\": \"FB01\",\n \"registered\": \"Y\"\n }\n ]\n}"}],"_postman_id":"e6f3b8b2-0b5a-41be-8813-5071b912f762"},{"name":"Update taxpayer","id":"4549579b-731e-4e14-bfa4-7294e6a67cd1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-api-key","value":"960528cd-7718-4b2b-b192-648e3da56dd7","type":"text"}],"body":{"mode":"raw","raw":"{\n \"taxpayer_id\": 106,\n \"webhook_url\": \"https://bla.some.bla/webhook\"\n}","options":{"raw":{"language":"json"}}},"url":"https://star-client-api.untied.io/updateTaxpayer","description":"Triggers an update. Employment/income data will be fetched from HMRC for the specfied taxpayer.
\nOn completion a POST request will be made to the specified webhook_url with the following payload:
\n{\n \"taxpayer_id\": <taxpayer_id>,\n \"type\": \"data_update\",\n \"status\": \"complete\"\n}\n\nOnce the operation is complete the data can be retrieved via the Get taxpayer (/taxpayer) endpoint.
\nIf an error occurred when retrieving data the status returned to the webhook will be \"error\":
\n{\n \"taxpayer_id\": <taxpayer_id>,\n \"type\": \"data_update\",\n \"status\": \"error\"\n}\n\nContact untied if an error is received.
\n","urlObject":{"path":["updateTaxpayer"],"host":["https://star-client-api.untied.io"],"query":[],"variable":[]}},"response":[{"id":"e4920a27-4d23-479f-95d1-f54cbc98dceb","name":"Update taxpayer","originalRequest":{"method":"POST","header":[{"key":"x-api-key","value":"960528cd-7718-4b2b-b192-648e3da56dd7","type":"text"}],"body":{"mode":"raw","raw":"{\n \"client_id\": 106,\n \"return_url\": \"https://bla.some.bla/webhook\"\n}","options":{"raw":{"language":"json"}}},"url":"https://star-client-api.untied.io/updateTaxpayer"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"content-type","value":"application/json"},{"key":"x-cloud-trace-context","value":"f4ac68d3be782a0f820f80224e1c8e36;o=1"},{"key":"date","value":"Tue, 19 Sep 2023 21:05:45 GMT"},{"key":"server","value":"Google Frontend"},{"key":"Content-Length","value":"50"},{"key":"via","value":"1.1 google, 1.1 google"},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"update requested\",\n \"status\": \"success\"\n}"}],"_postman_id":"4549579b-731e-4e14-bfa4-7294e6a67cd1"},{"name":"Cancel taxpayer registration","id":"d62bb358-80c9-4f6b-8568-63c762039313","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-api-key","value":"960528cd-7718-4b2b-b192-648e3da56dd7","type":"text"}],"body":{"mode":"raw","raw":"{\n \"taxpayer_id\": 147,\n \"cancel_in_days\": 7\n}","options":{"raw":{"language":"json"}}},"url":"https://star-client-api.untied.io/cancelTaxpayer","description":"Cancels taxpayer registration. This removes the authorisation from HMRC and deletes all taxpayer data.
\nNote that this process is asynchronous and it can take a few seconds for the authorisation to be removed from HMRC. Therefore, during testing, please wait for the taxpayer to disappear from the taxpayer list before attempting to reinvite.
\nOptional: to delay cancellation set cancel_in_days to the number of days from the request that the authorisation should be cancelled. If omitted, or set to zero, authorisation is cancelled immediately.
\n","urlObject":{"path":["cancelTaxpayer"],"host":["https://star-client-api.untied.io"],"query":[],"variable":[]}},"response":[{"id":"35cbc166-3bbb-49ad-9154-868a515494cb","name":"Cancel Client Registration","originalRequest":{"method":"POST","header":[{"key":"x-api-key","value":"960528cd-7718-4b2b-b192-648e3da56dd7","type":"text"}],"body":{"mode":"raw","raw":"{\n \"client_id\": 147\n}","options":{"raw":{"language":"json"}}},"url":"https://star-client-api.untied.io/cancelClient"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"content-type","value":"application/json"},{"key":"x-cloud-trace-context","value":"8697c716dd3d4ff3c444b65a09c957ac"},{"key":"date","value":"Mon, 25 Sep 2023 10:27:35 GMT"},{"key":"server","value":"Google Frontend"},{"key":"Content-Length","value":"50"},{"key":"via","value":"1.1 google, 1.1 google"},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"cancel requested\",\n \"status\": \"success\"\n}"}],"_postman_id":"d62bb358-80c9-4f6b-8568-63c762039313"}],"id":"c97b9c66-c451-48aa-b0f2-61b9c0eadd08","_postman_id":"c97b9c66-c451-48aa-b0f2-61b9c0eadd08","description":""},{"name":"Guides","item":[{"name":"Authorise Single Taxpayer and Retrieve Data","item":[],"id":"7cfdfa6f-0cd2-425c-911e-839aedc461c7","description":"Steps for authorising a taxpayer and retrieving their employment record:
\nPOST the taxpayer's NINO and DoB to /invite:
\n{ \n \"synchronous\": \"N\",\n \"taxpayers\": [\n {\"nino\": \"NX112233A\", \"dob\": \"1975-01-26\", \"email\": \"\", \"ref\": \"\"}\n ], \n \"webhook_url\": \"https://someplace.com/star/star-webhook\"\n}\n\nAfter a few seconds the web hook will receive notification that the invite has been created:
\n{\n \"batch_id\": 99,\n \"type\": \"invite\",\n \"status\": \"complete\"\n}\n\nGET /batch/99
\n{\n \"batch\": {\n \"batch_email\": \"\",\n \"batch_ref\": \"f1d5ca0d-bd9e-49b5-82cd-cfa4fd493e50\",\n \"id\": 99,\n \"send_invite_emails\": \"N\"\n },\n \"taxpayers\": [\n {\n \"custom_ref\": \"f1d5ca0d-bd9e-49b5-82cd-cfa4fd493e50\",\n \"dob\": \"Wed, 20 Feb 1980 00:00:00 GMT\",\n \"email\": \"\",\n \"error\": \"N\",\n \"found\": \"Y\",\n \"id\": 111,\n \"invite_url\": \"https://star-client-api.untied.io/authLink/87b50ee8-2e26-4e92-b633-5ff66795439c\",\n \"message\": \"Invited\",\n \"nino\": \"NX112233B\",\n \"processed\": \"Y\",\n \"registered\": \"N\",\n \"requested\": \"Tue, 11 Jul 2023 09:43:24 GMT\"\n }\n ],\n \"status\": \"success\"\n}\n\nPull out the invite_url. Send the client to this URL asking them to confirm the authorisation.
\nOnce the user has accepted the authorisation your webhook will be notified that the invite was accepted:
\n{\n \"batch_id\": <batch_id>,\n \"taxpayer_id\": <taxpayer_id>,\n \"type\": \"invite_accepted\",\n \"status\": \"complete\"\n}\n\nAfter a few more seconds the webhook should report that data update is complete:
\n{\n \"taxpayer_id\": <taxpayer_id>,\n \"type\": \"data_update\",\n \"status\": \"complete\"\n}\n\nTo fetch the most up to date data use GET /taxpayer
\nGET /taxpayer/111
\n{\n \"allowances\": [],\n \"debts\": [\n {\n \"id\": 954,\n \"name\": \"Underpaid tax for earlier years included in tax code for 2022 to 2023 Also shown as 'amount of underpaid tax for earlier years' on a client's P2, 'PAYE Coding Notice'. \",\n \"tax_year\": \"2022-2023\",\n \"updated\": \"Thu, 25 May 2023 13:00:26 GMT\",\n \"value\": \"£0.00\"\n },\n {\n \"id\": 955,\n \"name\": \"Underpaid tax for 2022 to 2023 included in tax code for 2023 to 2024 Also shown as 'estimated underpayment for 2022 to 2023' on a client's P2, 'PAYE Coding Notice'. \",\n \"tax_year\": \"2022-2023\",\n \"updated\": \"Thu, 25 May 2023 13:00:26 GMT\",\n \"value\": \"£0.00\"\n },\n {\n \"id\": 956,\n \"name\": \"Outstanding debt included in tax code for 2022 to 2023 Debts may relate to Self Assessment, tax credits or National Insurance Class 2.\",\n \"tax_year\": \"2022-2023\",\n \"updated\": \"Thu, 25 May 2023 13:00:26 GMT\",\n \"value\": \"£0.00\"\n },\n {\n \"id\": 2169,\n \"name\": \"Underpaid tax for earlier years included in tax code for 2022 to 2023 Also shown as 'amount of underpaid tax for earlier years' on a client's P2, 'PAYE Coding Notice'. \",\n \"tax_year\": \"2022-2023\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:22 GMT\",\n \"value\": \"£0.00\"\n },\n {\n \"id\": 2170,\n \"name\": \"Underpaid tax for 2022 to 2023 included in tax code for 2023 to 2024 Also shown as 'estimated underpayment for 2022 to 2023' on a client's P2, 'PAYE Coding Notice'. \",\n \"tax_year\": \"2022-2023\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:22 GMT\",\n \"value\": \"£0.00\"\n },\n {\n \"id\": 2171,\n \"name\": \"Outstanding debt included in tax code for 2022 to 2023 Debts may relate to Self Assessment, tax credits or National Insurance Class 2.\",\n \"tax_year\": \"2022-2023\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:22 GMT\",\n \"value\": \"£0.00\"\n }\n ],\n \"employments\": [\n {\n \"allowances\": {\n \"Gift aid payments\": \"£385\",\n \"Personal allowance\": \"£0\"\n },\n \"benefits\": {},\n \"deductions\": {\n \"Adjustment to rate band\": {\n \"deducted\": \"£63,307\",\n \"owed\": \"£0\"\n },\n \"Car benefit\": {\n \"deducted\": \"£996\",\n \"owed\": \"\"\n }\n },\n \"end_date\": \"Ongoing\",\n \"id\": 7916,\n \"name\": \"ACME ONE LTD\",\n \"paye_ref\": \"504/2609\",\n \"start_date\": \"6 Apr 2017\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"K6390X\",\n \"tax_paid\": \"£51\",\n \"tax_year\": \"2023-2024\",\n \"taxable_income\": \"£3,150\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:18 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7917,\n \"name\": \"COMPANY TWO LTD\",\n \"paye_ref\": \"120/EE01587\",\n \"start_date\": \"6 Mar 2020\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"D1X\",\n \"tax_paid\": \"£250\",\n \"tax_year\": \"2023-2024\",\n \"taxable_income\": \"£1,250\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:19 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7918,\n \"name\": \"COMPANY THREE LTD\",\n \"paye_ref\": \"120/KE46334\",\n \"start_date\": \"6 Apr 2022\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"BR\",\n \"tax_paid\": \"£6,180\",\n \"tax_year\": \"2023-2024\",\n \"taxable_income\": \"£30,900\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:19 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7919,\n \"name\": \"ACME ONE LTD\",\n \"paye_ref\": \"504/2609\",\n \"start_date\": \"6 Apr 2017\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£406.20\",\n \"tax_year\": \"2022-2023\",\n \"taxable_income\": \"£11,920.50\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:21 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7920,\n \"name\": \"COMPANY TWO LTD\",\n \"paye_ref\": \"120/EE01587\",\n \"start_date\": \"6 Mar 2020\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£993.40\",\n \"tax_year\": \"2022-2023\",\n \"taxable_income\": \"£6,666.66\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:21 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7921,\n \"name\": \"COMPANY THREE LTD\",\n \"paye_ref\": \"120/KE46334\",\n \"start_date\": \"6 Apr 2022\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£1,120\",\n \"tax_year\": \"2022-2023\",\n \"taxable_income\": \"£5,600\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:22 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7924,\n \"name\": \"ACME ONE LTD\",\n \"paye_ref\": \"504/2609\",\n \"start_date\": \"6 Apr 2017\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£4,072.10\",\n \"tax_year\": \"2021-2022\",\n \"taxable_income\": \"£9,564\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:24 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7926,\n \"name\": \"COMPANY TWO LTD\",\n \"paye_ref\": \"120/EE01587\",\n \"start_date\": \"6 Mar 2020\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£16,000\",\n \"tax_year\": \"2021-2022\",\n \"taxable_income\": \"£80,000.04\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:24 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7930,\n \"name\": \"COMPANY TWO LTD\",\n \"paye_ref\": \"504/2609\",\n \"start_date\": \"6 Apr 2017\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£144\",\n \"tax_year\": \"2020-2021\",\n \"taxable_income\": \"£8,712\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:26 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7932,\n \"name\": \"ACME ONE LTD\",\n \"paye_ref\": \"120/EE01587\",\n \"start_date\": \"6 Mar 2020\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£10,582.80\",\n \"tax_year\": \"2020-2021\",\n \"taxable_income\": \"£46,666.69\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:26 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7938,\n \"name\": \"COMPANY TWO LTD\",\n \"paye_ref\": \"504/2609\",\n \"start_date\": \"6 Apr 2017\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£151.60\",\n \"tax_year\": \"2019-2020\",\n \"taxable_income\": \"£8,628\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:28 GMT\"\n },\n {\n \"allowances\": {},\n \"benefits\": {},\n \"deductions\": {},\n \"end_date\": \"Ongoing\",\n \"id\": 7940,\n \"name\": \"ACME ONE LTD\",\n \"paye_ref\": \"120/EE01587\",\n \"start_date\": \"6 Mar 2020\",\n \"status\": \"Current\",\n \"student_loan_repaid\": null,\n \"tax_code\": \"unknown\",\n \"tax_paid\": \"£0\",\n \"tax_year\": \"2019-2020\",\n \"taxable_income\": \"£0\",\n \"type\": \"employment\",\n \"updated\": \"Mon, 10 Jul 2023 13:00:28 GMT\"\n }\n ],\n \"statePensions\": [],\n \"status\": \"success\",\n \"taxpayerInfo\": [\n {\n \"date_processed\": \"Mon, 10 Jul 2023 13:00:16 GMT\",\n \"dob\": \"Wed, 26 Jan 1972 00:00:00 GMT\",\n \"email\": \"fred@blogs.ai\",\n \"id\": 74,\n \"last_updated\": \"Wed, 17 May 2023 11:20:17 GMT\",\n \"name\": \"Fred Bloggs\",\n \"nino\": \"XX998877Z\",\n \"processed\": \"Y\",\n \"reference\": \"FB01\",\n \"registered\": \"Y\"\n }\n ]\n}\n\nOptionally and subject to agreed terms and conditions, the taxpayer authorisation can be cancelled:
\nPOST /cancelTaxpayer
\n{\n \"taxpayer_id\": 111\n}\n\nAfter a few seconds the taxpayer will be removed and GET /taxpayer will no longer retrieve it. A taxpayer cannot be reinvited until the taxpayer no longer exists in the list.
\n","_postman_id":"7cfdfa6f-0cd2-425c-911e-839aedc461c7"}],"id":"f0123dee-cc78-4cad-bcc0-3898abd2c692","_postman_id":"f0123dee-cc78-4cad-bcc0-3898abd2c692","description":""},{"name":"Test Data","item":[],"id":"427f9cb8-96e6-4696-afa6-c03909f10434","description":"The following test users will return canned test data:
\nInvite URLs for test users do not redirect to HMRC. Instead the invite is auto accepted and the page will show 'Invite accepted'.
\nOnce the invite has been accepted you can retrieve data. Data is synthetic and the same for each test user.
\nFor API keys that are set to sandbox only, inviting any other nino (live or otherwise) will result in an error.
\n","_postman_id":"427f9cb8-96e6-4696-afa6-c03909f10434"}],"event":[{"listen":"prerequest","script":{"id":"ef550e8c-8c7e-41fc-875e-ced533e8ac0a","type":"text/javascript","requests":{},"exec":[""]}},{"listen":"test","script":{"id":"66a4a212-a834-4e53-9791-56b5b97c7421","type":"text/javascript","requests":{},"exec":[""]}}],"variable":[{"key":"base_url","value":"https://star-client-api.untied.io"},{"key":"api_key","value":"960528cd-7718-4b2b-b192-648e3da56dd7"}]}