Handling Requests
Request
The following metadata are ALWAYS added in the Partner API request body:
| Metadata | Definition |
|---|---|
requestID | PHIL's unique identifier for the request. |
requestTimestamp | Timestamp for the request. Used for analytics and debugging purposes. |
{
"metadata": {
"requestID": "phil_request_id",
"responseTimestamp": "2024-09-11T11:58:00Z"
}
...
}The requestID is what we use to map Partner's data to ours. For every response, including all calls to our callback APIs, the requestID we sent must be returned back to us.
Response
In the response metadata, Partners are required to return the following:
| Metadata | Definition |
|---|---|
referenceID | Partner's unique identifier for the prescription. |
responseID | Partner's unique identifier for the response. This field will be used for debugging purposes. |
responseType | The type of the response. See Response Types below. |
responseTimestamp | Timestamp for the response. Used for debugging purposes. |
In addition, the requestID from the request metadata also needs to be returned so we can map your data with ours.
{
"requestID": "phil_request_id",
"metadata": {
"referenceID": "partner_reference_id",
"responseType": "RECEIVED",
"responseID": "partner_response_id",
"responseTimestamp": "2024-09-11T12:26:00Z"
}
}Response Types
For all APIs, there are different 200 response types:
| Response Type | Definition |
|---|---|
RECEIVED | The request has been received, but not yet processed. This requires a follow-up callback to confirm that the request has been completed and fully processed. |
CONFIRMED | The request has been completed and fully processed. This can be returned immediately as a response or asynchronously via the callback API. |
ERROR | The request was received but encountered an error during processing. An error type is required in the response body. |
Synchronous responses are preffered when processing our requests to reduce errors and confusion. However, if you need time to process our requests and can't support returning responses immediately, you can use Callbacks.
When returned in the response body, these response types are added in the response metadata.
For more information about error response types, see Error Handling.