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

> Documentation Index
> Fetch the complete documentation index at: https://docs.evidential.dev/llms.txt
> Use this file to discover all available pages before exploring further.

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

Path: Evidential Experiments API › Assignments

`POST /v1/experiments/{experiment_id}/assignments/{participant_id}/assign_with_filters`

URL: `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.

## Authentication

- `DatasourceApiKey`, apiKey, in header, header `X-API-Key`

## Path parameters

- `participant_id` (`get_assignment_filtered.path.participant_id`; string, required) — Your application's identifier for the participant.
- `experiment_id` (`get_assignment_filtered.path.experiment_id`; string, required) — The ID of the experiment to fetch.

## Query parameters

- `create_if_none` (`get_assignment_filtered.query.create_if_none`; boolean, optional) — Create an assignment if none exists. Set to false to check for an existing assignment without creating one.
  - default: `true`

## Request body

_Required._

- `properties` (`get_assignment_filtered.properties`; array of object, required) — Participant properties to match against the experiment's filters.
  - `field_name` (`get_assignment_filtered.properties.field_name`; string, required) — The name of the property. This must match a field_name defined on the experiment.
    - maxLength: `300` · minLength: `1`
  - `value` (`get_assignment_filtered.properties.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`

## Example request

```json
{
  "properties": [
    {
      "field_name": "field_name",
      "value": 0
    }
  ]
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url 'https://api.evidential.dev/v1/experiments/<experiment_id>/assignments/<participant_id>/assign_with_filters' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '
{
  "properties": [
    {
      "field_name": "field_name",
      "value": 0
    }
  ]
}
'
```

### TypeScript

```typescript
const url = 'https://api.evidential.dev/v1/experiments/<experiment_id>/assignments/<participant_id>/assign_with_filters';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'X-API-Key': '<X-API-Key>'},
  body: JSON.stringify({properties: [{field_name: 'field_name', value: 0}]})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.evidential.dev/v1/experiments/<experiment_id>/assignments/<participant_id>/assign_with_filters"

payload = { "properties": [
        {
            "field_name": "field_name",
            "value": 0
        }
    ] }
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "<X-API-Key>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 200

Successful Response

#### Example

```json
{
  "experiment_id": "string",
  "participant_id": "string",
  "assignment": {
    "arm_id": "string",
    "participant_id": "string",
    "cluster_key": "string",
    "arm_name": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "strata": [
      {
        "field_name": "field_name",
        "strata_value": "string"
      }
    ],
    "observed_at": "2019-08-24T14:15:22Z",
    "outcome": 0,
    "autofailed_outcome": true,
    "context_values": [
      0
    ]
  }
}
```

- `experiment_id` (`get_assignment_filtered.response.200.experiment_id`; string, required)
- `participant_id` (`get_assignment_filtered.response.200.participant_id`; string, required)
- `assignment` (`get_assignment_filtered.response.200.assignment`; any of, required) — Null if no assignment. Strata are not included.
  - any of the following:
    - `Assignment`
      - `arm_id` (`Assignment.arm_id`; string, required) — ID of the arm this participant was assigned to. Same as Arm.arm_id.
      - `participant_id` (`Assignment.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` (`Assignment.arm_name`; string, required) — The arm this participant was assigned to. Same as Arm.arm_name.
        - maxLength: `100`
      - `cluster_key` (`Assignment.cluster_key`; any of, optional) — Cluster identifier for this participant. Present for cluster-randomized preassigned experiments.
        - any of the following: `string`, `null`
      - `created_at` (`Assignment.created_at`; any of, optional) — The date and time the assignment was created.
        - any of the following: `string`, `null`
      - `strata` (`Assignment.strata`; any of, 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` (`Assignment.strata.1.field_name`; string, required)
              - maxLength: `300` · minLength: `1`
            - `strata_value` (`Assignment.strata.1.strata_value`; any of, optional)
              - any of the following: `string`, `null`
          - `null`
      - `observed_at` (`Assignment.observed_at`; any of, optional) — The date and time the outcome was recorded.
        - any of the following: `string`, `null`
      - `outcome` (`Assignment.outcome`; any of, optional) — The observed outcome for this assignment.
        - any of the following: `number`, `null`
      - `autofailed_outcome` (`Assignment.autofailed_outcome`; any of, 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` (`Assignment.context_values`; any of, 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.

#### Example

```json
{}
```

### 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.

#### Example

```json
{}
```

### 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.

#### Example

```json
{}
```

### 422

Validation Error

#### Example

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
```

- `detail` (`get_assignment_filtered.response.422.detail`; array of object, optional)
  - `loc` (`get_assignment_filtered.response.422.detail.loc`; array\<any of\>, required)
    - any of the following: `string`, `integer`
  - `msg` (`get_assignment_filtered.response.422.detail.msg`; string, required)
  - `type` (`get_assignment_filtered.response.422.detail.type`; string, required)
  - `input` (`get_assignment_filtered.response.422.detail.input`; unknown, optional)
  - `ctx` (`get_assignment_filtered.response.422.detail.ctx`; object, optional)


Source: https://docs.evidential.dev/api/assignments/assign-with-filters/index.md
