Requisitions API

​

Resource

​

Requisition

• dataProviders/{data_provider}/requisitions/{requisition} (canonical)
• measurementConsumers/{measurement_consumer}/measurements/{measurement}/requisitions/{requisition}

​

DuchyEntry

​

Refusal

​

FulfillmentContext

​

Methods

​

ListRequisitions

message ListRequisitionsRequest {
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  int32 page_size = 2;
  string page_token = 3;
  Filter filter = 4;
}

message ListRequisitionsResponse {
  repeated Requisition requisitions = 1;
  string next_page_token = 2;
}

​

GetRequisition

message GetRequisitionRequest {
  string name = 1 [(google.api.field_behavior) = REQUIRED];
}

​

RefuseRequisition

message RefuseRequisitionRequest {
  string name = 1 [(google.api.field_behavior) = REQUIRED];
  Requisition.Refusal refusal = 2 [(google.api.field_behavior) = REQUIRED];
  string etag = 3;
}

• Refusing a requisition causes the parent measurement to fail permanently.
• Only use for permanent failures (e.g., invalid spec, insufficient privacy budget).
• For transient errors, retry instead of refusing.
• The etag parameter provides optimistic concurrency control.

​

FulfillDirectRequisition

message FulfillDirectRequisitionRequest {
  string name = 1 [(google.api.field_behavior) = REQUIRED];
  EncryptedMessage encrypted_result = 4;
  fixed64 nonce = 3 [(google.api.field_behavior) = REQUIRED];
  string certificate = 5;
  Requisition.FulfillmentContext fulfillment_context = 6;
  string etag = 7;
}

message FulfillDirectRequisitionResponse {
  Requisition.State state = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

• The Direct protocol is used for simple, direct data provision.
• The result must be encrypted with the measurement consumer’s public key.
• The nonce must match the one from the encrypted requisition spec.
• The etag parameter provides optimistic concurrency control.

​

State Transitions

  [Created]
      |
      v
  UNFULFILLED
      |
      +---> FULFILLED (terminal)
      +---> REFUSED (terminal)
      +---> WITHDRAWN (terminal)

​

State Descriptions

• UNFULFILLED: The requisition has been created but not yet fulfilled by the data provider.
• FULFILLED: The data provider has successfully fulfilled the requisition by providing the requested data.
• REFUSED: The data provider refused to fulfill the requisition (causes measurement to fail).
• WITHDRAWN: The requisition was withdrawn (e.g., measurement was cancelled).

​

Refusal Justifications

​

CONSENT_SIGNAL_INVALID

• A digital signature cannot be verified using the specified certificate
• An encrypted value cannot be decrypted using the specified key
• Cryptographic validation fails

​

SPEC_INVALID

• The encrypted requisition spec contains invalid data
• The time interval is invalid (e.g., end_time before start_time)
• Configuration is not supported by the DataProvider

​

INSUFFICIENT_PRIVACY_BUDGET

• The requisition would exceed available privacy budget
• Differential privacy constraints prevent fulfillment
• Privacy parameters are exhausted

​

UNFULFILLABLE

• Data corruption prevents fulfillment
• Internal DataProvider failure occurs
• The requisition should be fulfillable but cannot be for technical reasons

​

DECLINED

• DataProvider policy prevents fulfillment
• Business reasons prevent fulfillment
• Reasons not expressible through other justifications

​

Workflow

​

DataProvider Perspective

1. List Requisitions: Poll for new UNFULFILLED requisitions using ListRequisitions.
2. Decrypt Spec: Decrypt the encrypted_requisition_spec using your private key.
3. Validate Request: Check signatures, validate spec, check privacy budget.
4. Collect Data: Gather the requested data from your EventGroups.
5. Compute Result: Calculate the measurement result according to the spec.
6. Encrypt Result: Encrypt the result using the measurement consumer’s public key.
7. Fulfill or Refuse:
   • Success: Call FulfillDirectRequisition with the encrypted result
   • Failure: Call RefuseRequisition with appropriate justification

​

MeasurementConsumer Perspective

1. Create Measurement: Creating a measurement automatically creates requisitions.
2. Monitor Progress: Poll measurement state or list requisitions to track fulfillment.
3. Handle Failures: If a requisition is refused, the measurement will fail with details.
4. Retrieve Results: When all requisitions are fulfilled and computation completes, decrypt results.