Endpoints for registering where the HIE pushes claim, preauth and authorization status changes.
List callback endpoints
Lists the endpoints registered under a tenant, optionally narrowed to one entity_type.
This route resolves the path value as a tenant ID first and falls back to a facility_fr_code - it does
not accept a tenant_code. Use the same identifier you registered the endpoint under, or the facility's FR
code; a tenant code returns an empty array rather than an error.
A tenant holds at most one endpoint per entity_type, so filtering by entity_type returns at most one
result.
Only active records are returned. The endpoint list is filtered to is_active: true, and each endpoint's
embedded operations array is filtered the same way, so a paused endpoint or operation is absent rather
than shown as inactive. An empty array therefore means "nothing registered, or registered and paused". To
inspect a paused operation, read it directly by its operation_id.
Related documentation: Manage callback endpoints
path Parameters
tenant_idYour tenant ID, or the facility_fr_code the endpoints were registered against. A tenant_code is not resolved on this route.
query Parameters
entity_typeNarrow the result to a single entity type: claim, preauth or authorization.
List callback endpoints › Responses
Endpoints retrieved successfully
auth_typeHow the HIE authenticates when it calls your endpoint. none is the only value you can set yourself: every other value needs a secret_ref, and secrets are provisioned by the HIE rather than through the API.
base_urlScheme and host each operation's path is appended to.
created_atWhen the endpoint was registered.
endpoint_idThe identifier to use when registering operations, and on the update and delete routes.
entity_typeWhich entity's status changes reach this endpoint: claim, preauth or authorization.
environmentWhich of your environments this endpoint belongs to. Only production and sandbox are accepted; prod is rejected.
facility_fr_codeFacility Registry code this endpoint serves. The fallback selector at delivery time.
Static headers sent on every delivery to this endpoint.
idInternal row identifier. Address the endpoint by endpoint_id, not by this.
is_activeWhether this endpoint is eligible for delivery. Nothing is delivered while it is false, and no error is raised.
nameYour label for the endpoint.
The operations registered under this endpoint. Empty until you register one - an endpoint on its own delivers nothing.
retry_configcircularsecret_refReference to the credential the HIE uses. Empty when auth_type is none. The credential itself is never returned.
tenant_codePrimary selector, matched against the tenant_code the EDI backend publishes before facility_fr_code is tried. Normally the same value as your client ID, and unique to you.
tenant_idThe tenant that owns this endpoint, as resolved from the path when it was registered.
timeout_msHow long the HIE waits for your response before treating the attempt as failed.
updated_atWhen the endpoint was last changed.
Register a callback endpoint
Registers the endpoint the HIE calls when an entity's status changes. This is the first of the two calls that set up status callbacks; the second registers an operation on the endpoint returned here.
Register one endpoint per entity type - a facility may hold at most one endpoint for each of claim,
preauth and authorization.
The path value is resolved against the tenant table as a tenant ID first and retried as a tenant_code,
so either handle registers the endpoint. Your tenant_code is normally the same value as your client ID and
is unique to you. If neither matches a tenant, the response is a 404.
The response is the bare endpoint object. Keep its endpoint_id: you need it to register the operation.
Related documentation: Register a callback endpoint
path Parameters
tenant_idYour tenant ID, or your tenant_code - normally the same value as your client ID.
Register a callback endpoint › Request Body
auth_typeHow the HIE authenticates to your endpoint. Required. none is the only value you can set yourself; every other value also requires secret_ref, and secrets are stored by the HIE out of band.
base_urlScheme and host the operation path is appended to. Required, and must be an absolute URL.
entity_typeWhich entity's status changes this endpoint receives. Required, and must be one of the three values listed. A facility holds at most one endpoint per entity type, so register a separate endpoint for each kind you want.
environmentRequired. production or sandbox. prod is rejected.
nameYour label for the endpoint. Required. It is not parsed and does not have to be unique.
facility_fr_codeFacility Registry code this endpoint serves. Used as the fallback selector at delivery time when no tenant matches tenant_code, and as a lookup key on GET /tenants/{tenant_id}/endpoints.
Static headers sent on every delivery to this endpoint. Use them for routing or tracing values, never for credentials.
Retry policy for deliveries to this endpoint. Omit it to accept the platform default.
secret_refReference to the credential the HIE uses for this endpoint. Required whenever auth_type is not none. The HIE issues the value; there is no API route that stores a secret.
tenant_codeSelector matched first at delivery time against the tenant_code the EDI backend publishes. This is normally the same value as your client ID, and it is unique to you. Defaults to the resolved tenant's own code when omitted, which is usually what you want.
timeout_msHow long the HIE waits for your response before treating the attempt as failed. Defaults to 60000.
Register a callback endpoint › Responses
Endpoint created successfully
auth_typeHow the HIE authenticates when it calls your endpoint. none is the only value you can set yourself: every other value needs a secret_ref, and secrets are provisioned by the HIE rather than through the API.
base_urlScheme and host each operation's path is appended to.
created_atWhen the endpoint was registered.
endpoint_idThe identifier to use when registering operations, and on the update and delete routes.
entity_typeWhich entity's status changes reach this endpoint: claim, preauth or authorization.
environmentWhich of your environments this endpoint belongs to. Only production and sandbox are accepted; prod is rejected.
facility_fr_codeFacility Registry code this endpoint serves. The fallback selector at delivery time.
Static headers sent on every delivery to this endpoint.
idInternal row identifier. Address the endpoint by endpoint_id, not by this.
is_activeWhether this endpoint is eligible for delivery. Nothing is delivered while it is false, and no error is raised.
nameYour label for the endpoint.
The operations registered under this endpoint. Empty until you register one - an endpoint on its own delivers nothing.
retry_configcircularsecret_refReference to the credential the HIE uses. Empty when auth_type is none. The credential itself is never returned.
tenant_codePrimary selector, matched against the tenant_code the EDI backend publishes before facility_fr_code is tried. Normally the same value as your client ID, and unique to you.
tenant_idThe tenant that owns this endpoint, as resolved from the path when it was registered.
timeout_msHow long the HIE waits for your response before treating the attempt as failed.
updated_atWhen the endpoint was last changed.
List callback operations
Lists the operations registered under an endpoint, optionally narrowed to one action.
An endpoint holds at most one operation per action, so filtering by action=status_changed returns at most
one result.
Only active operations are returned, so a paused operation is absent rather than shown as inactive. Read
it directly by its operation_id to see it.
On this GET the tenant_id segment is genuinely ignored - the handler never reads it - so any non-empty
value works. Unlike the POST, nothing is written.
Related documentation: Manage callback endpoints
path Parameters
tenant_idIgnored on this route - the handler never reads it. Any non-empty value works; sending the facility FR code keeps your logs consistent with the POST.
endpoint_idThe endpoint_id returned when the endpoint was registered.
query Parameters
actionNarrow the result to a single action. For status callbacks this is status_changed.
List callback operations › Responses
Operations retrieved successfully
actionThe event this operation answers. status_changed for status callbacks.
created_atWhen the operation was registered.
endpoint_idThe parent endpoint this operation belongs to.
Static headers sent on this operation's deliveries, on top of the endpoint's own.
idInternal row identifier. Address the operation by operation_id, not by this.
is_activeWhether this operation is eligible for delivery. Both the endpoint and the operation must be active.
methodHTTP method the HIE uses when calling your endpoint. DELETE is accepted at registration but is not supported at delivery time, so use POST for status callbacks.
nameYour label for the operation.
operation_idThe identifier to use on the read, update and delete routes.
pathPath appended to the endpoint's base_url unless path_url_override is set.
path_url_overrideAbsolute URL that replaces base_url + path when set. Returned as null when unused.
request_content_typeContent type of the delivered body.
Retry policy applied when a delivery attempt does not return a 2xx.
timeout_msResponse deadline for this operation. null means the endpoint's value applies.
updated_atWhen the operation was last changed.
Register a callback operation
Registers what the HIE does on an endpoint. This is the second of the two calls that set up status callbacks, and nothing is delivered until it succeeds.
Send action: status_changed. The same action serves all three entity types - the parent endpoint's
entity_type is what tells a claim integration from a preauth or authorization one.
The operation is attached using endpoint_id alone. The tenant_id segment is not resolved as a tenant
here: it is written into the endpoint's facility_fr_code if that column is still empty, so send the
facility's FR code rather than a placeholder.
Supply path, or path_url_override to send this one callback to an absolute URL that ignores the
endpoint's base_url.
Related documentation: Register a callback operation
path Parameters
tenant_idThis segment is not a tenant lookup. On this POST it is used to backfill the parent endpoint's facility_fr_code when that column is empty, so send the facility FR code. Do not send a placeholder such as _: it would be stored as the facility code and break delivery's fallback selector. If you set facility_fr_code when you created the endpoint, this value is ignored.
endpoint_idThe endpoint_id returned when the endpoint was registered.
Register a callback operation › Request Body
actionThe event this operation answers. Required. For status callbacks it is always status_changed, whatever the entity type.
methodHTTP method the HIE calls with. Required, one of GET, POST, PUT, PATCH, DELETE. Use POST: DELETE passes validation here but fails at delivery time.
nameYour label for the operation. Required.
Static headers for this operation, in addition to the endpoint's own.
pathPath appended to the endpoint's base_url. Required unless you send path_url_override.
path_url_overrideAbsolute URL that replaces base_url + path entirely. Use it when this one callback must go somewhere other than the endpoint's host; the endpoint's base_url is then ignored for this operation.
request_content_typeContent type of the delivered body. Defaults to application/json, which is what the status-callback payload is.
Retry policy for deliveries to this endpoint. Omit it to accept the platform default.
timeout_msResponse deadline for this operation, overriding the endpoint's value.
Register a callback operation › Responses
Operation created successfully
actionThe event this operation answers. status_changed for status callbacks.
created_atWhen the operation was registered.
endpoint_idThe parent endpoint this operation belongs to.
Static headers sent on this operation's deliveries, on top of the endpoint's own.
idInternal row identifier. Address the operation by operation_id, not by this.
is_activeWhether this operation is eligible for delivery. Both the endpoint and the operation must be active.
methodHTTP method the HIE uses when calling your endpoint. DELETE is accepted at registration but is not supported at delivery time, so use POST for status callbacks.
nameYour label for the operation.
operation_idThe identifier to use on the read, update and delete routes.
pathPath appended to the endpoint's base_url unless path_url_override is set.
path_url_overrideAbsolute URL that replaces base_url + path when set. Returned as null when unused.
request_content_typeContent type of the delivered body.
Retry policy applied when a delivery attempt does not return a 2xx.
timeout_msResponse deadline for this operation. null means the endpoint's value applies.
updated_atWhen the operation was last changed.
Delete a callback endpoint
Deletes a callback endpoint together with every operation registered under it. Deliveries stop immediately.
To pause callbacks without losing the registration, PATCH the endpoint with is_active: false instead.
The endpoint is addressed by its own ID, so this route is not nested under a tenant. The response carries
only a message.
Related documentation: Manage callback endpoints
path Parameters
endpoint_idThe endpoint_id returned when the endpoint was registered.
Delete a callback endpoint › Responses
Endpoint deleted successfully. The body carries only message
@Description Response data payload containing operation details @Example {"status": "success"}
message@Description Success message describing the operation result @Example "Visit has been successfully started"
Update a callback endpoint
Partially updates a callback endpoint. Every field present in the body is applied; omitted fields are left untouched, and an empty body is rejected with a 400.
Use is_active: false to pause deliveries without deleting the registration, and is_active: true to resume
them. A paused endpoint raises no error - it simply receives nothing, which is the first thing to check
when callbacks stop arriving.
The endpoint is addressed by its own ID, so this route is not nested under a tenant. The response is the complete endpoint object, not just the changed fields.
Related documentation: Manage callback endpoints
path Parameters
endpoint_idThe endpoint_id returned when the endpoint was registered.
Update a callback endpoint › Request Body
auth_typeNew authentication mechanism. Changing it to anything other than none needs a secret_ref the HIE has issued.
base_urlNew scheme and host. Must be an absolute URL.
entity_typeMove this endpoint to a different entity type. Must be one of the three values listed. Changing it re-points a live integration, so it is rarely what you want on a working registration.
environmentproduction or sandbox.
Replaces the stored header map wholesale rather than merging into it.
is_activeSet to false to stop delivery without deleting the registration. Nothing is delivered while this is false, and no error is raised - the first thing to check when callbacks stop arriving.
nameNew label for the endpoint.
secret_refNew credential reference, issued by the HIE.
tenant_codeNew primary selector, matched against the tenant_code the EDI backend publishes.
timeout_msNew response deadline in milliseconds.
Update a callback endpoint › Responses
Endpoint updated successfully
auth_typeHow the HIE authenticates when it calls your endpoint. none is the only value you can set yourself: every other value needs a secret_ref, and secrets are provisioned by the HIE rather than through the API.
base_urlScheme and host each operation's path is appended to.
created_atWhen the endpoint was registered.
endpoint_idThe identifier to use when registering operations, and on the update and delete routes.
entity_typeWhich entity's status changes reach this endpoint: claim, preauth or authorization.
environmentWhich of your environments this endpoint belongs to. Only production and sandbox are accepted; prod is rejected.
facility_fr_codeFacility Registry code this endpoint serves. The fallback selector at delivery time.
Static headers sent on every delivery to this endpoint.
idInternal row identifier. Address the endpoint by endpoint_id, not by this.
is_activeWhether this endpoint is eligible for delivery. Nothing is delivered while it is false, and no error is raised.
nameYour label for the endpoint.
The operations registered under this endpoint. Empty until you register one - an endpoint on its own delivers nothing.
retry_configcircularsecret_refReference to the credential the HIE uses. Empty when auth_type is none. The credential itself is never returned.
tenant_codePrimary selector, matched against the tenant_code the EDI backend publishes before facility_fr_code is tried. Normally the same value as your client ID, and unique to you.
tenant_idThe tenant that owns this endpoint, as resolved from the path when it was registered.
timeout_msHow long the HIE waits for your response before treating the attempt as failed.
updated_atWhen the endpoint was last changed.
Read a callback operation
Reads a single callback operation by its own ID. Unlike the list route this does not need the parent endpoint, and it returns inactive operations too - which makes it the quickest way to confirm whether an operation has been paused.
Related documentation: Manage callback endpoints
path Parameters
operation_idThe operation_id returned when the operation was registered.
Read a callback operation › Responses
Operation retrieved successfully
actionThe event this operation answers. status_changed for status callbacks.
created_atWhen the operation was registered.
endpoint_idThe parent endpoint this operation belongs to.
Static headers sent on this operation's deliveries, on top of the endpoint's own.
idInternal row identifier. Address the operation by operation_id, not by this.
is_activeWhether this operation is eligible for delivery. Both the endpoint and the operation must be active.
methodHTTP method the HIE uses when calling your endpoint. DELETE is accepted at registration but is not supported at delivery time, so use POST for status callbacks.
nameYour label for the operation.
operation_idThe identifier to use on the read, update and delete routes.
pathPath appended to the endpoint's base_url unless path_url_override is set.
path_url_overrideAbsolute URL that replaces base_url + path when set. Returned as null when unused.
request_content_typeContent type of the delivered body.
Retry policy applied when a delivery attempt does not return a 2xx.
timeout_msResponse deadline for this operation. null means the endpoint's value applies.
updated_atWhen the operation was last changed.
Delete a callback operation
Deletes a callback operation. The parent endpoint is left in place, so deliveries stop but the registration remains and a replacement operation can be added.
To pause without deleting, PATCH the operation with is_active: false instead.
Related documentation: Manage callback endpoints
path Parameters
operation_idThe operation_id returned when the operation was registered.
Delete a callback operation › Responses
Operation deleted successfully. The body carries only message
@Description Response data payload containing operation details @Example {"status": "success"}
message@Description Success message describing the operation result @Example "Visit has been successfully started"
Update a callback operation
Partially updates a callback operation. Every field present in the body is applied; omitted fields are left untouched, and an empty body is rejected with a 400.
Use is_active: false to pause deliveries for this operation. Both the endpoint and the operation must be
active for anything to arrive, and neither raises an error while paused.
The response is the complete operation object, not just the changed fields.
Related documentation: Manage callback endpoints
path Parameters
operation_idThe operation_id returned when the operation was registered.
Update a callback operation › Request Body
actionNew action. Changing it away from status_changed stops status callbacks reaching this operation.
Replaces the stored header map wholesale rather than merging into it.
is_activeSet to false to stop delivery without deleting the operation. Both the endpoint and the operation must be active for anything to arrive, and an inactive record raises no error.
methodNew HTTP method, one of GET, POST, PUT, PATCH, DELETE.
nameNew label for the operation.
pathNew path, appended to the endpoint's base_url.
path_url_overrideNew absolute URL, replacing base_url + path for this operation.
request_content_typeNew content type for the delivered body.
timeout_msNew response deadline for this operation, in milliseconds.
Update a callback operation › Responses
Operation updated successfully
actionThe event this operation answers. status_changed for status callbacks.
created_atWhen the operation was registered.
endpoint_idThe parent endpoint this operation belongs to.
Static headers sent on this operation's deliveries, on top of the endpoint's own.
idInternal row identifier. Address the operation by operation_id, not by this.
is_activeWhether this operation is eligible for delivery. Both the endpoint and the operation must be active.
methodHTTP method the HIE uses when calling your endpoint. DELETE is accepted at registration but is not supported at delivery time, so use POST for status callbacks.
nameYour label for the operation.
operation_idThe identifier to use on the read, update and delete routes.
pathPath appended to the endpoint's base_url unless path_url_override is set.
path_url_overrideAbsolute URL that replaces base_url + path when set. Returned as null when unused.
request_content_typeContent type of the delivered body.
Retry policy applied when a delivery attempt does not return a 2xx.
timeout_msResponse deadline for this operation. null means the endpoint's value applies.
updated_atWhen the operation was last changed.