Skip to content
Navigation

Get or create an Online A/B assignment with server-side filtering

POST
https://api.evidential.dev/v1/experiments/{experiment_id}/assignments/{participant_id}/assign_with_filters

Gets or creates an arm assignment for a participant on experiments using server-side filtering. If an assignment already exists, that assignment is returned and the properties in the request body are ignored.

If there are no filters on the experiment, use the get_assignment endpoint.

Authorization

  • DatasourceApiKey
    API key in header
    required

    X-API-Key: <token>

Path parameters

  • participant_id
    string
    required

    Your application's identifier for the participant.

  • experiment_id
    string
    required

    The ID of the experiment to fetch.

Query parameters

  • create_if_none
    optional
    boolean

    Create an assignment if none exists. Set to false to check for an existing assignment without creating one.

    default: true

Request body JSON required

  • properties
    array of
    object
    required

    Participant properties to match against the experiment's filters.

    • field_name
      string
      required

      The name of the property. This must match a field_name defined on the experiment.

      maxLength: 300 · minLength: 1
    • value
      PropertyValueTypes
      required

      The value of the property.

      Any of the following:

      • StrictInt

        Any of the following:

        • integer
        • null
      • StrictFloat

        Any of the following:

        • number
        • null
      • string
      • boolean
      • null

Returns

200

Successful Response

JSON
  • experiment_id
    string
    required
  • participant_id
    string
    required
  • assignment
    required

    Null if no assignment. Strata are not included.

    Any of the following:

    • Assignment
      • arm_id
        string
        required

        ID of the arm this participant was assigned to. Same as Arm.arm_id.

      • participant_id
        string
        required

        Unique identifier for the participant. This is the primary key for the participant in the data warehouse.

        maxLength: 64
      • arm_name
        string
        required

        The arm this participant was assigned to. Same as Arm.arm_name.

        maxLength: 100
      • cluster_key
        optional

        Cluster identifier for this participant. Present for cluster-randomized preassigned experiments.

        Any of the following:

        • string
        • null
      • created_at
        optional

        The date and time the assignment was created.

        Any of the following:

        • string
        • null
      • strata
        optional

        List of properties and their values for this participant used for stratification or tracking metrics. If stratification is not used, this will be None.

        Any of the following:

        • array<unknown>
          • field_name
            string
            required
            maxLength: 300 · minLength: 1
          • strata_value
            optional

            Any of the following:

            • string
            • null
        • null
      • observed_at
        optional

        The date and time the outcome was recorded.

        Any of the following:

        • string
        • null
      • outcome
        optional

        The observed outcome for this assignment.

        Any of the following:

        • number
        • null
      • autofailed_outcome
        optional

        Whether Evidential failed this outcome automatically (true) or a real outcome was observed (false). Null if no outcome was recorded.

        Any of the following:

        • boolean
        • null
      • context_values
        optional

        List of context values for this assignment. If no contexts are used, this will be None.

        Any of the following:

        • array<number>
        • null
    • null

400

The request is invalid. Check that the request body matches the required structure and that all required fields and headers are present.

403

You did not provide a valid API key, or your API key does not have permission for this operation.

Tip: Check that the API key in the X-API-Key header has access to the data source or experiment.

404

The resource was not found, or you do not have access to it.

Tip: Check that the API key in the X-API-Key header has access to the data source or experiment.

422

Validation Error
JSON
  • detail
    optional
    array of
    object
    • loc
      array of
      required

      Any of the following:

      • string
      • integer
    • msg
      string
      required
    • type
      string
      required
    • input
      optional
      unknown
    • ctx
      optional
      object

Type to search…

↑↓ navigate↵ selectEsc close