GET Results Letters events

Request results letters events with a client program.

Request

Endpoint

GET {clientId}/api/v1/letters-feed?programName=someProgram&startDate=01/01/2000&startEvent=date_eventId

The GET Results letters events endpoint requires the following information in the headers of an HTTP request:

HTTP Header	Description
Authorization	The HTTP Authorization request header contains the credentials to authenticate a user agent with a server.
Accept	The HTTP Accept request header contains information about the content types, expressed as MIME types, that the client can understand. The MIME type for the GET Results letters events request is application/json

Path parameters

Parameter	Description	Type	Required/Optional
clientId	The clientId is a unique code that is provided by LetsGetChecked. The code is a number between 0 and 9999.	string	Required

Query parameters

Parameter	Description	Type	Required/Optional
programName	The LetsGetChecked program name	string	Required
startDate	The start date from which a client wants to start their query. LetsGetChecked expects an ISO 8601 UTC date format	string	Required (if no startEvent is provided)
startEvent	Get events published after a specific event. The event key is composed by the event creation timestamp and the event id	string	Required (if no startDate is provided)

Response

Status Codes

Status Code	Description
200	Returned whenever one or more result letter events are found.
400	Returned whenever a param is send in an invalid format.
401	Returned whenever the Authorization header is not sent or is not a valid one.
404	Returned whenever a result letter event is not found.
503	Returned whenever the service is unavailable.
500	Returned whenever some generic error occurred in the server.

The sample response is a single JSON object that contains the following fields:

Property	Description	Type
next_url	Next url to use to get the next batch of events	string
items	Items associated with the results letter	list of objects(item)
item/id	The unique id of the event	string
item/url	The url to download the letter related to the event	string
item/date_published	The timestamp for published event, in UTC time, in ISO 8601 format	string
item/_data	Specific information associated with the results letter including results letter type, program name and barcode	object(_data)
item/_data/type	The results Letter type. The following values are possible: patient pcp	string
item/_data/programName	The LetsGetChecked program name	string
item/_data/barcode	Formatted as LGC-0000-0000-0000, where 0 indicates any digit	string

Sample Response

{
    "next_url": "{LGC-API}/1111/api/v1/letters-feed?programname=TestProgram&startEvent=638090378343289129_acddc326-866f-4081-a7cf-6e4e47376f68",
    "items": [
        {
            "id": "2b0fca70-3428-49f7-bb43-f1f594897365",
            "url": "{LGC-API}/api/v1/letters/patient_LGC-2787-3959-3483",
            "date_published": "2022-11-09T14:56:49.959516Z",
            "_data": {
                "type": "patient",
                "programName": "TestProgram",
                "barcode": "LGC-2887-3959-3483"
            }
        },
        {
            "id": "7bff71d7-de37-4b1e-a4a8-38adee3c2a0e",
            "url": "{LGC-API}/api/v1/letters/patient_LGC-8522-6687-9040",
            "date_published": "2022-11-10T12:00:34.6678993Z",
            "_data": {
                "type": "pcp",
                "programName": "TestProgram",
                "barcode": "LGC-8622-6687-9040"
            }
        }
    ]
}

info

The Get Results Letters Events pagination
The request for results letters events only brings a set of events (10), the rest of events the user can get by using the value that comes in the property next_url on the response. After requesting the events, the user should save this url, in order to keep getting new events in the subsequent requests.

If the request brings all the events or the client reached the end of the pagination the next_url will bring the following response:

{
    "next_url": null,
    "items": []
}