REST API for the Data Exchange domain — the facade for all interactions between the blueprint and external agencies and data sources (IRS, SSA, USCIS SAVE, state wage databases, and others).
Calling domains initiate service calls by POSTing to /service-calls. The request carries no PII — adapters retrieve sensitive fields from the source domain using requestingResourceId and the resource type declared in the ExternalService catalog. Results are delivered via the data-exchange.call.completed event and queryable via the event log.
Context passthrough: calling domains attach namespace-keyed metadata to a service call (e.g., PUT /service-calls/{id}/metadata/intake) before or at submission. That metadata is echoed back in the result event so the calling domain's rules can route the result to the right record.
Status: Alpha — Breaking changes expected.
https://api.example.com/data-exchangeServices
ExternalService catalog — the configured external data sources available in this deployment.
▶
GET
/services
List external services
#
Retrieve the catalog of external services available in this deployment. All entries are config-managed — defined in data-exchange-config.yaml and seeded at startup. States add entries via overlay; no write endpoints are provided.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| ▶q | string | query | Search query using field:value syntax. Multiple conditions separated by | |
| limit | integer | query | Maximum number of items to return (1-100). |
|
| offset | integer | query | Number of items to skip before collecting results. |
|
| ▶sort | string | query | Comma-separated list of fields to sort the response by. Prefix a field | |
| serviceType | ▶ ServiceType | query | Filter by service type. |
▶
GET
/services/{serviceId}
Get an external service
#
Retrieve a single external service catalog entry by identifier.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| serviceId | string | path | ✓ | Unique identifier of the external service catalog entry. |
ServiceCalls
External service call lifecycle — submission through resolution.
▶
GET
/service-calls
List service calls
#
Retrieve a paginated list of external service calls.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| ▶q | string | query | Search query using field:value syntax. Multiple conditions separated by | |
| limit | integer | query | Maximum number of items to return (1-100). |
|
| offset | integer | query | Number of items to skip before collecting results. |
|
| ▶sort | string | query | Comma-separated list of fields to sort the response by. Prefix a field | |
| requestingResourceId | string | query | Filter by the requesting resource ID. |
|
| serviceType | ▶ ServiceType | query | Filter by service type (e.g., |
|
| status | ▶ ExternalServiceCallStatus | query | Filter by call status. |
▶
POST
/service-calls
Submit a service call
#
Submit a request to call an external service. The request body carries no PII — adapters retrieve sensitive fields from the source domain using requestingResourceId and the resource type declared in the ExternalService catalog entry.
Submissions are deduplicated by requestingResourceId + serviceId. If a pending call already exists for the same pair, the server returns the existing call record rather than submitting a duplicate.
▶
GET
/service-calls/{serviceCallId}
Get a service call
#
Retrieve a single service call by identifier.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| serviceCallId | string | path | ✓ | Unique identifier of the service call. |
▶
PUT
/service-calls/{serviceCallId}/metadata/{domain}
Set domain metadata on a service call
#
Attach namespace-keyed metadata from the calling domain to a service call. Used for context passthrough — the calling domain stores identifiers it needs to resume when a result arrives (e.g., the verification ID to update). The metadata object is echoed back verbatim in the result event under event.data.metadata.{domain}.
Replaces any existing metadata for the given domain namespace. Other domains' namespaces are unaffected.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| serviceCallId | string | path | ✓ | Unique identifier of the service call. |
| domain | enum | path | ✓ | The calling domain attaching its metadata namespace. enum case-management client-management communication data-exchange document-management eligibility identity-access intake platform scheduling workflow |
▶
DELETE
/service-calls/{serviceCallId}/metadata/{domain}
Remove domain metadata from a service call
#
Remove the calling domain's entire metadata namespace from a service call.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| serviceCallId | string | path | ✓ | Unique identifier of the service call. |
| domain | enum | path | ✓ | The calling domain attaching its metadata namespace. enum case-management client-management communication data-exchange document-management eligibility identity-access intake platform scheduling workflow |