---
title: "Get or create a CMAB assignment for a participant"
---

> 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 a CMAB assignment for a participant

Path: Evidential Experiments API › Assignments

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

URL: `https://api.evidential.dev/v1/experiments/{experiment_id}/assignments/{participant_id}/assign_cmab`

Gets or creates an arm assignment for a participant. Used only for CMAB experiments. If an
assignment already exists, `context_inputs` in the request body may be null. If you provide it
anyway, it is ignored.

## Authentication

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

## Path parameters

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

## Query parameters

- `create_if_none` (`get_assignment_cmab.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._

- `context_inputs` (`get_assignment_cmab.context_inputs`; any of, required) — The context values for the assignment, one for each context defined on the experiment. Values are matched to contexts by context_id, not by position in the list. May be null when you retrieve an existing assignment. Otherwise, valid inputs are required.
  - any of the following:
    - `array<unknown>`
      - `context_id` (`get_assignment_cmab.context_inputs.1.context_id`; string, required) — Unique identifier for the context.
      - `context_value` (`get_assignment_cmab.context_inputs.1.context_value`; number, required) — Value of the context.
    - `null`
- `type` (`get_assignment_cmab.type`; string, optional)
  - default: `"cmab_assignment"`

## Example request

```json
{
  "type": "cmab_assignment",
  "context_inputs": [
    {
      "context_id": "1",
      "context_value": 2.5
    }
  ]
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url 'https://api.evidential.dev/v1/experiments/<experiment_id>/assignments/<participant_id>/assign_cmab' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '
{
  "type": "cmab_assignment",
  "context_inputs": [
    {
      "context_id": "1",
      "context_value": 2.5
    }
  ]
}
'
```

### TypeScript

```typescript
const url = 'https://api.evidential.dev/v1/experiments/<experiment_id>/assignments/<participant_id>/assign_cmab';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'X-API-Key': '<X-API-Key>'},
  body: JSON.stringify({
    type: 'cmab_assignment',
    context_inputs: [{context_id: '1', context_value: 2.5}]
  })
};

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_cmab"

payload = {
    "type": "cmab_assignment",
    "context_inputs": [
        {
            "context_id": "1",
            "context_value": 2.5
        }
    ]
}
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_cmab.response.200.experiment_id`; string, required)
- `participant_id` (`get_assignment_cmab.response.200.participant_id`; string, required)
- `assignment` (`get_assignment_cmab.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_cmab.response.422.detail`; array of object, optional)
  - `loc` (`get_assignment_cmab.response.422.detail.loc`; array\<any of\>, required)
    - any of the following: `string`, `integer`
  - `msg` (`get_assignment_cmab.response.422.detail.msg`; string, required)
  - `type` (`get_assignment_cmab.response.422.detail.type`; string, required)
  - `input` (`get_assignment_cmab.response.422.detail.input`; unknown, optional)
  - `ctx` (`get_assignment_cmab.response.422.detail.ctx`; object, optional)


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