documenter.getpostman.com Open in urlscan Pro
2606:4700:4400::6812:2196  Public Scan

Form analysis
0 forms found in the DOM

Text Content

 * Body
 * Headers (5)

 * Body
 * Headers (6)

 * Body
 * Headers (5)

 * Body
 * Headers (6)




Public


Documentation Settings

ENVIRONMENT
No Environment

LAYOUT
Double Column

LANGUAGE
cURL - cURL



STAR Client API
Introduction
Endpoints
Guides


STAR CLIENT API

API for untied STAR (Secure tax authorisation and reporting) service.

Provides API access to the functionality at https://asr.untied.io/. An API key
is required. Check in Settings or contact untied for access.


ENDPOINTS




POSTINVITE

https://star-client-api.untied.io/invite

Create invite batch. Use this to invite taxpayers to give you access to their
income records.

If 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.

The invite email template and other settings can be configured in your dashboard
at https://asr.untied.io/

Body parameters:

   
 * taxpayers: array of taxpayers to invite
   
 * batch_email: where to send the batch processing report
   
 * batch_ref: optional - if omitted a GUID will be created
   
 * send_invite_emails: optional - default is "N". If "Y" invite links will be
   sent to taxpayers
   
 * webhook_url: webhook url which is POSTed to with updates. See below.
   
 * synchronous: 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).
   
 * auto_update: optional. Default: "Y". If set to "N" a data update will not
   take place on invite acceptance.
   

Note 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.

Webhook payloads

Invite complete. When the batch of invites has been processed. Check the batch
with GET /batch/ to find the status of each taxpayer's invite.

json


{
  "batch_id": <batch_id>,
  "type": "invite",
  "status": "complete"
}

If any taxpayers in the batch exist in your account and have accepted an invite
already you will see something like the following:

json


{
  "batch_id": <batch_id>,
  "taxpayers_already_registered": [
        {
            "id": 196,
            "nino": "NX112233A"
        }
  ],
  "type": "invite",
  "status": "complete"
}

If all the taxpayers passed are already registered there is nothing to do and
therefore the webhook will not fire.

Invite accepted. When a user has accepted an invite:

json


{
  "batch_id": <batch_id>,
  "taxpayer_id": <taxpayer_id>,
  "type": "invite_accepted",
  "status": "complete"
}

Data update. As long as auto_update is not "N" data will be requested as soon as
the client accepts the invite.

JSON

json


{
   "taxpayer_id": <taxpayer_id>,  
   "type": "data_update",
   "status": "complete"
}

If the taxpayer actively declines the invite, "invite_declined" will be sent to
the webhook:

json


{
  "batch_id": <batch_id>,
  "taxpayer_id": <taxpayer_id>,
  "type": "invite_declined",
  "status": "complete"
}

HEADERS
x-api-key

960528cd-7718-4b2b-b192-648e3da56dd7

Bodyraw (json)
View More
json


{
    "batch_email": "marcus@untied.io",
    "batch_ref": "MJT12ABC",
    "send_invite_emails": "Y",
    "taxpayers": [
        {"nino": "NX112233B", "dob": "1980-02-20", "email": "user1@somewhere.com", "ref": ""},
        {"nino": "NX112233C", "dob": "1990-02-20", "email": "user2@somewhere.com", "ref": ""}
    ],
    "webhook_url": "https://someplace.com/webhook"
}

Example Request
invite

View More
curl


curl --location 'https://star-client-api.untied.io/invite' \
--header 'x-api-key: 960528cd-7718-4b2b-b192-648e3da56dd7' \
--data-raw '{
    "batch_email": "marcus@untied.io",
    "batch_ref": "MJT12ABC",
    "send_invite_emails": "Y",
    "taxpayers": [
        {"nino": "NX112233B", "dob": "1980-02-20", "email": "user1@somewhere.com", "ref": ""},
        {"nino": "NX112233C", "dob": "1990-02-20", "email": "user2@somewhere.com", "ref": ""}
    ]
}'

200 OK
Example Response
 * Body
 * Headers (5)

json


{
  "batch_id": 54,
  "status": "success"
}

Server

Werkzeug/2.3.4 Python/3.11.3

Date

Tue, 11 Jul 2023 09:43:24 GMT

Content-Type

application/json

Content-Length

35

Connection

close


GETLIST INVITE BATCHES

https://star-client-api.untied.io/batches

List invite batches.

HEADERS
x-api-key

960528cd-7718-4b2b-b192-648e3da56dd7

Example Request
invite batches example

curl


curl --location 'https://star-client-api.untied.io/batches' \
--header 'x-api-key: 960528cd-7718-4b2b-b192-648e3da56dd7'

200 OK
Example Response
 * Body
 * Headers (6)

View More
json


{
  "batches": [
    {
      "batch_email": "tin.demo@untied.io",
      "batch_ref": "6413544d162a4",
      "id": 25,
      "send_invite_emails": "N"
    },
    {
      "batch_email": "support@untied.io",
      "batch_ref": "Batch today",
      "id": 26,
      "send_invite_emails": "N"
    },
    {
      "batch_email": "support@untied.io",
      "batch_ref": "645392eaa07b4",
      "id": 33,
      "send_invite_emails": "N"
    },
    {
      "batch_email": "tin.demo@untied.io",
      "batch_ref": "645a0cff07f3f",
      "id": 34,
      "send_invite_emails": "N"
    },
    {
      "batch_email": "support@untied.io",
      "batch_ref": "645e441eab959",
      "id": 35,
      "send_invite_emails": "N"
    },
    {
      "batch_email": "support@untied.io",
      "batch_ref": "646f6fbe3dc1a",
      "id": 38,
      "send_invite_emails": "N"
    },
    {
      "batch_email": "support@untied.io",
      "batch_ref": "64773d967c075",
      "id": 40,
      "send_invite_emails": "N"
    },
    {
      "batch_email": "support@untied.io",
      "batch_ref": "6479a5da29405",
      "id": 41,
      "send_invite_emails": "N"
    },
    {
      "batch_email": "support@untied.io",
      "batch_ref": "6479aa38aca14",
      "id": 42,
      "send_invite_emails": "N"
    },
    {
      "batch_email": "support@untied.io",
      "batch_ref": "ABC1",
      "id": 43,
      "send_invite_emails": "Y"
    },
    {
      "batch_email": "support@untied.io",
      "batch_ref": "TT1",
      "id": 44,
      "send_invite_emails": "Y"
    },
    {
      "batch_email": "marcus@untied.io",
      "batch_ref": "MJT12ABC",
      "id": 54,
      "send_invite_emails": "Y"
    }
  ],
  "status": "success"
}

content-type

application/json

X-Cloud-Trace-Context

cee24bd6e77375e70f06306367f0646c

Date

Tue, 11 Jul 2023 10:32:16 GMT

Server

Google Frontend

Content-Length

1172

Alt-Svc

h3=":443"; ma=2592000,h3-29=":443"; ma=2592000


GETGET INVITE BATCH

https://star-client-api.untied.io/batch/54

Retrieve a specific batch including all invited taxpayers and their status.

The 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.

If 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.

If an error occurred when creating an invite 'error' will be 'Y' and the error
message will be in the 'message' attribute. Possible errors include:

   

 * "Service unavailable" - an error occurred trying to access HMRC's invite
   service

   

 * "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.

   

 * "NINO error"

   

 * "NINO and DOB do not match"

   

If the invite process has not yet completed or if there is an error, invite_url
will be null and found will be "N".

While it is possible to poll /batch and check these values it is more efficient
to specify a webhook on the /invite.

HEADERS
x-api-key

960528cd-7718-4b2b-b192-648e3da56dd7

Example Request
get invite batch example

curl


curl --location 'https://star-client-api.untied.io/batch/54' \
--header 'x-api-key: 960528cd-7718-4b2b-b192-648e3da56dd7'

200 OK
Example Response
 * Body
 * Headers (5)

View More
json


{
  "batch": {
    "batch_email": "sssss@xxxaaa.io",
    "batch_ref": "MJT12ABC",
    "id": 54,
    "send_invite_emails": "Y"
  },
  "taxpayers": [
    {
      "custom_ref": "MJT12ABC",
      "dob": "Wed, 20 Feb 1980 00:00:00 GMT",
      "email": "user1@somewhere.com",
      "error": "Y",
      "found": "N",
      "id": 111,
      "invite_url": "https://star-client-api.untied.io/authLink/87b50ee8-2e26-4e92-b633-5ff66795439c",
      "message": "NINO and DOB do not match",
      "nino": "NX112233B",
      "processed": "Y",
      "registered": "N",
      "requested": "Tue, 11 Jul 2023 09:43:24 GMT"
    },
    {
      "custom_ref": "MJT12ABC",
      "dob": "Tue, 20 Feb 1990 00:00:00 GMT",
      "email": "user2@somewhere.com",
      "error": "Y",
      "found": "N",
      "id": 112,
      "invite_url": "https://star-client-api.untied.io/authLink/87b50ee8-2e26-4e92-b633-5ff66795439c",
      "message": "NINO and DOB do not match",
      "nino": "NX112233C",
      "processed": "Y",
      "registered": "N",
      "requested": "Tue, 11 Jul 2023 09:43:24 GMT"
    }
  ],
  "status": "success"
}

Server

Werkzeug/2.3.4 Python/3.11.3

Date

Tue, 11 Jul 2023 10:14:07 GMT

Content-Type

application/json

Content-Length

666

Connection

close


GETLIST TAXPAYERS

https://star-client-api.untied.io/taxpayers

List all taxpayers that have completed invite processing successfully.
Registration status is checked daily.

To view status of recently invited taxpayers or to see ones that have failed use
the get batch endpoint.

HEADERS
x-api-key

960528cd-7718-4b2b-b192-648e3da56dd7

Example Request
List taxpayers

curl


curl --location 'https://star-client-api.untied.io/taxpayers' \
--header 'x-api-key: 960528cd-7718-4b2b-b192-648e3da56dd7'

200 OK
Example Response
 * Body
 * Headers (6)

View More
json


{
  "data": [
    {
      "date_processed": "Mon, 10 Jul 2023 13:00:16 GMT",
      "dob": "Wed, 26 Jan 1972 00:00:00 GMT",
      "email": "mike@somedomain.com",
      "id": 74,
      "last_updated": "Wed, 17 May 2023 11:20:17 GMT",
      "name": "Michael Smith",
      "nino": "NX998877C",
      "processed": "Y",
      "reference": "MS01",
      "registered": "Y"
    },
    {
      "date_processed": "Mon, 10 Jul 2023 14:00:29 GMT",
      "dob": "Sat, 25 Oct 1975 00:00:00 GMT",
      "email": "hello@mail.com",
      "id": 103,
      "last_updated": null,
      "name": "Susanne Price",
      "nino": "JE987651A",
      "processed": "Y",
      "reference": "MJT02",
      "registered": "Y"
    },
    {
      "date_processed": "Mon, 10 Jul 2023 14:00:19 GMT",
      "dob": "Sun, 22 Aug 1971 00:00:00 GMT",
      "email": "demo@place.com",
      "id": 100,
      "last_updated": null,
      "name": "KEITH SOPER",
      "nino": "NX003320A",
      "processed": "Y",
      "reference": "Ref1",
      "registered": "Y"
    }
  ],
  "status": "success"
}

content-type

application/json

X-Cloud-Trace-Context

64eb4cd36fc49c968ccf95808ee09497;o=1

Date

Tue, 11 Jul 2023 10:49:08 GMT

Server

Google Frontend

Content-Length

781

Alt-Svc

h3=":443"; ma=2592000,h3-29=":443"; ma=2592000