Data requests

A data request is a one-off, credential-bearing link that lets someone outside your team fill in a named subset of one passport's properties — a supplier confirming the capacity of a pack they shipped, a lab returning a test result. The recipient needs no Synex account and never sees the rest of your data: the link is emailed to them, and opening it renders a form holding exactly the properties you listed and nothing else.

Neither data_requests:read nor data_requests:write is in a key's default set, and neither is ontology-scopable. Grant them explicitly when the key is minted.

The data request model

The credentials appear exactly once

The 201 from POST /v1/data_requests carries three fields no other response does: token, secret, and the assembled url that combines them. Every other response uses the credential-free shape — every read, every list row, and every event payload.

That is also why a dreq_ public id had to be minted at all: if a request were addressed by its token, then every read of the list would be a handout of the credential, and data_requests:read would quietly be permission to fill in other people's forms.

The operational consequence is blunt: if the link is lost, revoke the request and create another. It cannot be recovered, by you or by support.

Status

expired rows survive — they are not cleaned up — and they are the usual reason a list holds a link nobody can use any more. Filter them out if you are showing outstanding work.

exhausted exists for completeness and is not normally observable. The fulfil path deletes the request the moment its last use is consumed, so an exhausted request stops existing rather than lingering in the list. Do not build a workflow that waits for a request to turn exhausted; watch for the data_request.fulfilled event, or for the request to disappear.

List data requests

curl -G https://api.synexcloud.com/v1/data_requests \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -d "passport=pass_3e9a1c5b7d2f4083"

{
  "object": "list",
  "data": [
    {
      "object": "data_request",
      "id": "dreq_4f7a2e9c1b5d8306",
      "passport": "pass_3e9a1c5b7d2f4083",
      "properties": ["property_capacity", "property_chemistry"],
      "recipient": "quality@nordvolt.example",
      "description": "Please confirm the shipped cell capacity.",
      "expiry_date": "2026-08-05T09:14:22Z",
      "max_uses": 1,
      "uses": 0,
      "status": "active",
      "created_at": "2026-07-22T09:14:22Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/data_requests"
}

Create a data request

curl https://api.synexcloud.com/v1/data_requests \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "passport": "pass_3e9a1c5b7d2f4083",
    "properties": ["property_capacity", "property_chemistry"],
    "recipient": "quality@nordvolt.example",
    "description": "Confirm shipped capacity and cell chemistry",
    "expiry_days": 14,
    "max_uses": 1
  }'

{
  "object": "data_request",
  "id": "dreq_4f7a2e9c1b5d8306",
  "passport": "pass_3e9a1c5b7d2f4083",
  "properties": ["property_capacity", "property_chemistry"],
  "recipient": "quality@nordvolt.example",
  "description": "Please confirm the shipped cell capacity.",
  "expiry_date": "2026-08-05T09:14:22Z",
  "max_uses": 1,
  "uses": 0,
  "status": "active",
  "created_at": "2026-07-22T09:14:22Z",
  "token": "7b1e4c02a9d63f85c0e27a4b8d1f6395",
  "secret": "4a0c9e75d2b81f36a7c5e0942b6d3f18e75c0a4b9d21f6837e0c5a49b2d67f13",
  "url": "https://app.synex.example/external/data-request/7b1e4c02a9d63f85c0e27a4b8d1f6395?secret=4a0c9e75d2b81f36a7c5e0942b6d3f18e75c0a4b9d21f6837e0c5a49b2d67f13"
}

Retrieve a data request

curl https://api.synexcloud.com/v1/data_requests/dreq_4f7a2e9c1b5d8306 \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "data_request",
  "id": "dreq_4f7a2e9c1b5d8306",
  "passport": "pass_3e9a1c5b7d2f4083",
  "properties": ["property_capacity", "property_chemistry"],
  "recipient": "quality@nordvolt.example",
  "description": "Please confirm the shipped cell capacity.",
  "expiry_date": "2026-08-05T09:14:22Z",
  "max_uses": 1,
  "uses": 0,
  "status": "active",
  "created_at": "2026-07-22T09:14:22Z"
}

Revoke a data request

curl -X DELETE https://api.synexcloud.com/v1/data_requests/dreq_4f7a2e9c1b5d8306 \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "data_request",
  "id": "dreq_4f7a2e9c1b5d8306",
  "deleted": true
}

When the third party submits

Two things a consumer of this API needs to know about the far end of the link.

Values are validated before they are stored. Everything the form posts runs through the same rejecting validator the import pipeline and the property-edit endpoint use, checked against each property's own definition. The submission is all-or-nothing: if any value is rejected the whole submission fails, nothing is written, and no use is consumed — the recipient can correct it and submit again against the same link. Properties the recipient left untouched are skipped rather than overwritten with blanks.

This is a change in behaviour: until recently whatever the form posted was written verbatim, so "about forty" could land in a measurement property and sit there looking like data.

It emits an event with a null actor. A successful submission puts data_request.fulfilled on the change feed. The recorded actor is null, which is correct rather than missing information — the party filling the form is a stranger holding a link, with no user account and no API key to attribute the change to.

The payload names which properties were filled and never what they were filled with. Event payloads travel to customer webhook endpoints, and the submitted values are the confidential half of the exchange, exactly as the token and secret are. If you need the values, read the passport.

Events

The submitted values also land as an ordinary passport update, so a consumer already watching passport.updated sees the change too — with the values, since a passport snapshot carries them. The two events describe the same write from different angles: one tells you a request was answered, the other tells you what the passport now says.