### Example Paginated API Request

Source: https://api-docs.userinterviews.com/reference/pagination

Demonstrates how to make a GET request to a list endpoint with pagination parameters for page size and page number.

```APIDOC
## GET /api/participants

### Description
Retrieves a list of participants with pagination.

### Method
GET

### Endpoint
/api/participants

### Query Parameters
- **page[size]** (integer) - Optional - The number of items to return per page. Defaults to 25, maximum is 200.
- **page[number]** (integer) - Optional - The desired page number to retrieve.

### Request Example
```shell
curl --request GET \
     --url "https://www.userinterviews.com/api/participants?page[size]=1&page[number]=2" \
     --header 'Accept: application/vnd.user-interviews.v2' \
     --header 'Content-Type: application/json'
```
```

--------------------------------

### Launch Recruit API Request Examples

Source: https://api-docs.userinterviews.com/reference/post_api-recruits-recruit-id-launches-1

Examples of how to launch a recruit using the API. Choose the language that best suits your needs.

```Shell
curl -X POST https://www.userinterviews.com/api/recruits/{recruit_id}/launches \
  -H "Content-Type: application/vnd.user-interviews.v2+json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

```Node.js
const fetch = require('node-fetch');

const recruitId = 'your_recruit_id';
const apiToken = 'YOUR_API_TOKEN';

fetch(`https://www.userinterviews.com/api/recruits/${recruitId}/launches`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/vnd.user-interviews.v2+json',
    'Authorization': `Bearer ${apiToken}`
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```Ruby
require 'net/http'
require 'uri'

uri = URI.parse('https://www.userinterviews.com/api/recruits/your_recruit_id/launches')

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-Type'] = 'application/vnd.user-interviews.v2+json'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body
```

```PHP
<?php

$recruitId = 'your_recruit_id';
$apiToken = 'YOUR_API_TOKEN';

$url = "https://www.userinterviews.com/api/recruits/{$recruitId}/launches";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/vnd.user-interviews.v2+json',
    "Authorization: Bearer {$apiToken}"
]);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}

curl_close($ch);

echo $response;
?>
```

```Python
import requests

recruit_id = 'your_recruit_id'
api_token = 'YOUR_API_TOKEN'

url = f"https://www.userinterviews.com/api/recruits/{recruit_id}/launches"
headers = {
    'Content-Type': 'application/vnd.user-interviews.v2+json',
    'Authorization': f'Bearer {api_token}'
}

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

print(response.json())
```

--------------------------------

### Example Error Response (401 Unauthorized)

Source: https://api-docs.userinterviews.com/reference/errors

This is an example of an error response when authentication fails due to an invalid API key.

```APIDOC
## Example Responses

**(401) Invalid API Key**

```json
{
  "errors": [
    {
      "status": "401",
      "source": null,
      "title": "Unauthorized",
      "detail": null
    }
  ]
}
```
```

--------------------------------

### Launch a Recruit

Source: https://api-docs.userinterviews.com/reference/post_api-recruits-recruit-id-launches-1

Launches a recruit to start recruiting participants. Edits to the recruit will be limited after launching.

```APIDOC
## POST https://www.userinterviews.com/api/recruits/{recruit_id}/launches

### Description
Launch a Recruit so that it will start recruiting participants. Once this has been done edits on the Recruit will be limited.

### Method
POST

### Endpoint
https://www.userinterviews.com/api/recruits/{recruit_id}/launches

### Parameters
#### Path Parameters
- **recruit_id** (string) - Required - The ID of the recruit to launch.

#### Request Body
- **data** (object) - Required - The data object for the launch request.
  - **data** (object) - Required - The data object containing launch details.
```

--------------------------------

### Example Paginated API Response Structure

Source: https://api-docs.userinterviews.com/reference/pagination

Illustrates the structure of a paginated API response, including the 'data' field and the 'meta.pagination' object.

```APIDOC
## Response Structure

### Description
Paginated responses include a `meta` object containing `pagination` details.

### Response
#### Success Response (200)
- **data** (array) - The list of requested resources.
- **meta** (object) - Contains pagination information.
  - **pagination** (object) - Details about the current pagination state.
    - **first** (integer) - The first page number.
    - **prev** (integer) - The previous page number.
    - **next** (integer) - The next page number.
    - **last** (integer) - The last page number.
    - **currentPage** (integer) - The current page number being viewed.
    - **offset** (integer) - The number of items skipped to reach the current page.
    - **perPage** (integer) - The number of items per page.
    - **totalEntries** (integer) - The total number of entries available.
    - **totalPages** (integer) - The total number of pages available.
    - **rangeFrom** (integer) - The starting index of the items on the current page.
    - **rangeTo** (integer) - The ending index of the items on the current page.

### Response Example
```json
{
  "data": [...],
  "meta": {
    "pagination": {
      "first": 1,
      "prev": 1,
      "next": 3,
      "last": 3,
      "currentPage": 2,
      "offset": 25,
      "perPage": 25,
      "totalEntries": 75,
      "totalPages": 3,
      "rangeFrom": 1,
      "rangeTo": 1
    }
  }
}
```
```

--------------------------------

### Example API Request with Filter

Source: https://api-docs.userinterviews.com/reference/filtering

This `curl` command demonstrates how to request unsubscribed participants by including the Base 64 encoded filter parameter in the API request URI.

```shell
curl --request GET \
     --url https://www.userinterviews.com/api/participants?filter=eyJ1bnN1YnNjcmliZWRBdCI6IHsiaXNOb3ROdWxsIjogInRydWUifX0= \
     --header 'Accept: application/vnd.user-interviews.v2' \
     --header 'user-interviews-apikey: <YOUR_API_KEY>' \
     --header 'Content-Type: application/json'
```

--------------------------------

### Example Paginated API Request

Source: https://api-docs.userinterviews.com/reference/pagination

Use query parameters 'page[size]' and 'page[number]' to specify the desired page size and number. The default page size is 25, and the maximum is 200.

```shell
curl --request GET \
     --url https://www.userinterviews.com/api/participants?page[size]=1&page[number]=2 \
     --header 'Accept: application/vnd.user-interviews.v2' \
     --header 'Content-Type: application/json'
```

--------------------------------

### Get Recruitment Groups

Source: https://api-docs.userinterviews.com/reference/get_api-recruitment-groups

Retrieves a list of recruitment groups. Supports pagination and filtering.

```APIDOC
## GET /groups

### Description
Retrieves a list of recruitment groups. Supports pagination and filtering.

### Method
GET

### Endpoint
/groups

### Query Parameters
- **offset** (integer) - Optional - The number of records to skip before starting to collect the result set.
- **perPage** (integer) - Optional - The numbers of records to return per page.

### Response
#### Success Response (200)
- **data** (array) - An array of recruitment group objects.
  - **id** (string) - The unique identifier for the group.
  - **name** (string) - The name of the group.
  - **createdAt** (string) - The date and time the group was created.
  - **updatedAt** (string) - The date and time the group was last updated.
  - **memberCount** (integer) - The number of members in the group.
  - **recruitCount** (integer) - The number of recruits associated with the group.
  - **recruitStatus** (string) - The status of recruits in the group.
  - **recruitStatusDescription** (string) - A description of the recruit status.
  - **recruitStatusColor** (string) - The color code associated with the recruit status.
  - **recruitStatusIcon** (string) - The icon associated with the recruit status.

#### Response Example
{
  "data": [
    {
      "id": "group_123",
      "name": "Beta Testers",
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:00:00Z",
      "memberCount": 50,
      "recruitCount": 25,
      "recruitStatus": "active",
      "recruitStatusDescription": "Actively participating",
      "recruitStatusColor": "#4CAF50",
      "recruitStatusIcon": "check_circle"
    }
  ]
}

#### Error Response (403)
- **description**: Forbidden - Private Preview
```

--------------------------------

### Get Recruit Participants

Source: https://api-docs.userinterviews.com/reference/get_api-recruits-recruit-id-participants-1

Retrieves a list of participants for a given recruit ID.

```APIDOC
## GET /api/recruits/{recruitId}/participants

### Description
Retrieves a list of participants associated with a specific recruit.

### Method
GET

### Endpoint
/api/recruits/{recruitId}/participants

### Parameters
#### Path Parameters
- **recruitId** (string) - Required - The unique identifier of the recruit.

### Response
#### Success Response (200)
- **firstName** (string) - The first name of the participant.
- **lastName** (string) - The last name of the participant.
- **status** (string) - The current status of the participant in the recruit process. Possible values include: approved, complete, fraudulent, no_show, potential, prequalified, qualified, qualified_needs_review, rejected, scheduled, task_started, task_submitted, unqualified, unsorted.
- **location** (string) - The locality, region, and country of the participant.
- **disqualificationReasons** (array) - A list of reasons why the participant was disqualified.
- **screenerResponses** (array) - An array of objects, where each object contains a question and the participant's response.
- **taskDetails** (object) - Details about the task assigned to the participant, including an expiration date.

#### Response Example
{
  "participants": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "status": "qualified",
      "location": "New York, NY, USA",
      "disqualificationReasons": [],
      "screenerResponses": [
        {
          "question": "What is your favorite color?",
          "response": "Blue"
        }
      ],
      "taskDetails": {
        "expiresAt": "2024-12-31T23:59:59Z"
      }
    }
  ]
}
```

--------------------------------

### Get Recruit Participants

Source: https://api-docs.userinterviews.com/reference/get_api-recruits-recruit-id-participants-1

Fetches a list of participants for a specified recruit ID. Supports filtering and pagination.

```APIDOC
## GET /api/recruits/{recruit_id}/participants

### Description
Retrieves a list of participants for a specific recruit.

### Method
GET

### Endpoint
/api/recruits/{recruit_id}/participants

### Parameters
#### Path Parameters
- **recruit_id** (string) - Required - The ID of the recruit to retrieve participants for.

#### Query Parameters
- **filter** (string) - Optional - A base64 encoded JSON string representing the filter criteria. Example: `eyJuYW1lIjoiSm9obiBEb2UifQ==`
- **page** (integer) - Optional - The page number to retrieve.
- **per_page** (integer) - Optional - The number of items to return per page.

### Response
#### Success Response (200)
- **data** (array) - An array of participant objects.
  - **id** (string) - The unique identifier for the participant.
  - **type** (string) - The type of the resource (e.g., 'participants').
  - **attributes** (object) - Contains the attributes of the participant.
  - **relationships** (object) - Contains relationships to other resources.
- **included** (array) - An array of related resources included in the response.
- **links** (object) - Contains links for pagination (self, first, prev, next, last).
- **meta** (object) - Contains metadata about the response, including pagination details.

#### Response Example
```json
{
  "data": [
    {
      "id": "participant_abc123",
      "type": "participants",
      "attributes": {
        "name": "Jane Doe",
        "email": "jane.doe@example.com"
      },
      "relationships": {}
    }
  ],
  "links": {
    "self": "https://api.example.com/v2/recruits/recruit_xyz789/participants?page=1",
    "first": "https://api.example.com/v2/recruits/recruit_xyz789/participants?page=1",
    "next": "https://api.example.com/v2/recruits/recruit_xyz789/participants?page=2",
    "last": "https://api.example.com/v2/recruits/recruit_xyz789/participants?page=5"
  },
  "meta": {
    "pagination": {
      "currentPage": 1,
      "offset": 0,
      "perPage": 25
    }
  }
}
```

#### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
- **422** - Invalid JSON in base64 filter parameter
```

--------------------------------

### Get Characteristic Options

Source: https://api-docs.userinterviews.com/reference/get_api-characteristics-characteristic-slug-options-1

Retrieves a list of options available for a specific characteristic. This is useful for understanding the possible values or selections for a given characteristic.

```APIDOC
## GET /api/characteristics/{characteristic_slug}/options

### Description
Retrieves a list of options for a specific characteristic.

### Method
GET

### Endpoint
/api/characteristics/{characteristic_slug}/options

### Parameters
#### Path Parameters
- **characteristic_slug** (string) - Required - The unique slug of the characteristic for which to retrieve options.

### Response
#### Success Response (200)
- **data** (array) - An array of characteristic options.
  - **id** (string) - The unique identifier for the option.
  - **type** (string) - The type of the option.
  - **attributes** (object) - The attributes of the option.
    - **name** (string) - The name of the option.
- **links** (object) - Links related to the response.
  - **self** (string) - A link to the returned dataset.
  - **first** (string) - A link to the first page of data.
  - **prev** (string, nullable) - A link to the previous page of data.
  - **next** (string, nullable) - A link to the next page of data.
  - **last** (string) - A link to the last page of data.
- **meta** (object) - Metadata about the response.
  - **pagination** (object) - Pagination details.
    - **currentPage** (integer) - The current page number.
    - **offset** (integer) - The offset for the current page.
    - **perPage** (integer) - The number of items per page.

#### Error Response (400)
- **description**: Invalid characteristic slug
```

--------------------------------

### Get Participant

Source: https://api-docs.userinterviews.com/reference/get_api-participants-id-2

Fetches a participant's data using their ID.

```APIDOC
## GET /participants/{id}

### Description
Retrieves details for a specific participant using their unique identifier.

### Method
GET

### Endpoint
/participants/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the participant.

### Response
#### Success Response (200)
- **data** (object) - Contains the participant's information.
  - **id** (string) - The participant's ID.
  - **type** (string) - The type of the resource (e.g., "participant").
  - **attributes** (object) - The participant's attributes.
    - **characteristics** (array) - A list of participant characteristics.
      - **name** (string) - The name of the characteristic.
      - **slug** (string) - The slug of the characteristic.
      - **type** (string) - The type of the characteristic.
      - **value** (string | boolean | integer) - The value of the characteristic.
    - **createdAt** (string) - The timestamp when the participant was created.
    - **email** (string) - The participant's email address.
    - **firstName** (string) - The participant's first name (nullable).
    - **labels** (array) - A list of labels associated with the participant.
      - **label** (string) - The label text.
      - **textColor** (string) - The text color of the label.
      - **labelColor** (string) - The background color of the label.
    - **lastName** (string) - The participant's last name (nullable).
    - **phone** (string) - The participant's phone number (nullable).
    - **source** (string) - The source of the participant data.
    - **subscribed** (boolean) - Indicates if the participant is subscribed.
    - **unsubscribed_at** (string) - The timestamp when the participant unsubscribed (nullable).

#### Response Example
{
  "data": {
    "id": "participant_id_123",
    "type": "participant",
    "attributes": {
      "characteristics": [
        {
          "name": "Age",
          "slug": "age",
          "type": "number",
          "value": 30
        }
      ],
      "createdAt": "2023-10-27T10:00:00Z",
      "email": "test@example.com",
      "firstName": "John",
      "labels": [
        {
          "label": "High Value",
          "textColor": "#FFFFFF",
          "labelColor": "#007BFF"
        }
      ],
      "lastName": "Doe",
      "phone": "+1234567890",
      "source": "web",
      "subscribed": true,
      "unsubscribed_at": null
    }
  }
}

#### Error Response (404)
- **description**: Invalid Participant ID
```

--------------------------------

### Get Prepaid Balances

Source: https://api-docs.userinterviews.com/reference/get_api-prepaid-balances

Fetches the current prepaid balance information.

```APIDOC
## GET /prepaid-balances

### Description
Retrieves the current prepaid balance information for the authenticated user.

### Method
GET

### Endpoint
/prepaid-balances

### Response
#### Success Response (200)
- **data** (object) - Contains the prepaid balance details.
  - **amount** (number) - The current balance amount.
  - **currency** (string) - The currency of the balance.
- **links** (object) - Pagination links.
  - **self** (string) - Link to the current page.
  - **first** (string) - Link to the first page.
  - **prev** (string) - Link to the previous page.
  - **next** (string) - Link to the next page.
  - **last** (string) - Link to the last page.
- **meta** (object) - Metadata about the response.
  - **pagination** (object) - Pagination details.
    - **currentPage** (integer) - The current page number.
    - **offset** (integer) - The offset for the current page.
    - **perPage** (integer) - The number of items per page.

#### Response Example
```json
{
  "data": {
    "amount": 100.50,
    "currency": "USD"
  },
  "links": {
    "self": "https://api.example.com/prepaid-balances?page=1",
    "first": "https://api.example.com/prepaid-balances?page=1",
    "prev": null,
    "next": null,
    "last": "https://api.example.com/prepaid-balances?page=1"
  },
  "meta": {
    "pagination": {
      "currentPage": 1,
      "offset": 0,
      "perPage": 20
    }
  }
}
```

#### Error Response (403)
- **description**: Forbidden - Private Preview
```

--------------------------------

### List Projects

Source: https://api-docs.userinterviews.com/reference/get_api-characteristics-2

Retrieves a list of projects with pagination details.

```APIDOC
## GET /projects

### Description
Retrieves a list of projects, supporting pagination.

### Method
GET

### Endpoint
/projects

### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.
- **perPage** (integer) - Optional - The number of items to return per page.

### Response
#### Success Response (200)
- **data** (array) - An array of project objects.
  - **createdAt** (string) - The creation timestamp of the project.
  - **id** (string) - The unique identifier of the project.
  - **name** (string) - The name of the project.
  - **slug** (string) - The slug of the project.
  - **type** (string) - The type of the project.
  - **updatedAt** (string) - The last update timestamp of the project.
- **meta** (object) - Pagination metadata.
  - **pagination** (object) - Details about the pagination.
    - **currentPage** (integer) - The current page number.
    - **first** (integer) - The first page number (nullable).
    - **last** (integer) - The last page number (nullable).
    - **next** (integer) - The next page number (nullable).
    - **offset** (integer) - The offset for the current page.
    - **perPage** (integer) - The number of items per page.
    - **prev** (integer) - The previous page number (nullable).
    - **totalEntries** (integer) - The total number of entries.

#### Response Example
{
  "data": [
    {
      "createdAt": "2023-10-27T10:00:00Z",
      "id": "proj_123",
      "name": "Example Project",
      "slug": "example-project",
      "type": "research",
      "updatedAt": "2023-10-27T10:00:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "currentPage": 1,
      "first": 1,
      "last": 10,
      "next": 2,
      "offset": 0,
      "perPage": 10,
      "prev": null,
      "totalEntries": 100
    }
  }
}
```

--------------------------------

### Get Participant by ID

Source: https://api-docs.userinterviews.com/reference/get_api-recruit-participants-participant-id-1

Fetches a participant's details using their ID.

```APIDOC
## GET /participants/{participantId}

### Description
Retrieves the details of a specific participant.

### Method
GET

### Endpoint
/participants/{participantId}

### Parameters
#### Path Parameters
- **participantId** (string) - Required - The unique identifier of the participant.

### Response
#### Success Response (200)
- **data** (object) - Contains the participant's data.
  - **id** (string) - The participant's ID.
  - **type** (string) - The type of the resource (e.g., "participants").
  - **attributes** (object) - Contains the participant's attributes.
  - **links** (object) - Contains links related to the participant.

#### Response Example
```json
{
  "data": {
    "id": "some_participant_id",
    "type": "participants",
    "attributes": {
      "email": "test@example.com",
      "name": "John Doe"
    },
    "links": {
      "self": "/participants/some_participant_id"
    }
  }
}
```

#### Error Response (401)
- **description**: Unauthorized

#### Error Response (404)
- **description**: participant not found
```

--------------------------------

### Create Recruit

Source: https://api-docs.userinterviews.com/reference/post_api-recruits

Creates a new recruit for a project. This involves defining project details, participant requirements, and session information.

```APIDOC
## POST /api/recruits

### Description
Creates a new recruit for a project.

### Method
POST

### Endpoint
/api/recruits

### Request Body
- **internalName** (string) - Required - Internal name for the project.
- **internalDescription** (string) - Optional - Internal description for the project.
- **numParticipants** (integer) - Required - How many participants should be recruited.
- **preparationInstructions** (string) - Optional - Instructions for participants before the task.
- **publicDescription** (string) - Required - A short description of the study for participants.
- **publicTitle** (string) - Required - A title for the study for participants.
- **recruitmentGroupId** (string) - Optional - The ID of the recruitment group to assign this recruit to. Set to null to remove from group.
- **requireApproval** (boolean) - Optional - Whether manual approval of participants is required. Defaults to false.
- **sessionDetails** (object) - Optional - Details about the study sessions.
  - **availabilityUrl** (string) - Required - URL for fetching availability.
  - **availabilityStartAt** (string, format: date) - Required - When availability starts.
  - **availabilityEndAt** (string, format: date) - Required - When availability ends.
  - **sessionDuration** (integer) - Required - The length of each session in minutes.
  - **sessionsWebhookUrl** (string, format: uri) - Required - Webhook for scheduled sessions.

### Request Example
```json
{
  "internalName": "Project Alpha",
  "numParticipants": 5,
  "publicDescription": "Study on user behavior",
  "publicTitle": "User Behavior Study",
  "sessionDetails": {
    "availabilityUrl": "https://example.com/availability",
    "availabilityStartAt": "2023-10-27",
    "availabilityEndAt": "2023-11-10",
    "sessionDuration": 30,
    "sessionsWebhookUrl": "https://example.com/webhook"
  }
}
```

### Response
#### Success Response (200)
- **recruitId** (string) - The ID of the created recruit.
- **projectId** (string) - The ID of the associated project.

#### Response Example
```json
{
  "recruitId": "recruit-12345",
  "projectId": "project-abcde"
}
```
```

--------------------------------

### Get Recruit by ID

Source: https://api-docs.userinterviews.com/reference/get_api-recruits-recruit-id

Retrieves detailed information about a specific recruit using their unique ID.

```APIDOC
## GET /api/recruits/{recruitId}

### Description
Retrieves detailed information about a specific recruit using their unique ID.

### Method
GET

### Endpoint
/api/recruits/{recruitId}

### Parameters
#### Path Parameters
- **recruitId** (string) - Required - The unique identifier of the recruit to retrieve.
```

--------------------------------

### Recruits Filtering Parameters

Source: https://api-docs.userinterviews.com/reference/post_api-recruits

This section details the parameters available for filtering recruits. It covers single-select characteristics like gender, home owner status, household income, industry, and level of education. For each characteristic, you can use either an exact match ($eq) with a single slug or a multiple selection ($in) with an array of slugs. The available options for these slugs are provided by the Characteristic options list endpoint.

```APIDOC
## Filtering Recruits

### Description
This API allows filtering recruits based on various demographic and professional characteristics. The filtering supports exact matches and multiple selections for single-select fields.

### Parameters

#### Query Parameters

- **single_select--gender** (object) - Required - Filters by gender. Supports `$eq` (string) for a single value or `$in` (array of strings) for multiple values.
- **single_select--home_owner** (object) - Required - Filters by home owner status. Supports `$eq` (string) for a single value or `$in` (array of strings) for multiple values.
- **single_select--household_income_in_usd** (object) - Required - Filters by household income in USD. Supports `$eq` (string) for a single value or `$in` (array of strings) for multiple values.
- **single_select--industry** (object) - Required - Filters by industry. Supports `$eq` (string) for a single value or `$in` (array of strings) for multiple values.
- **single_select--level_of_education** (object) - Required - Filters by level of education. Supports `$eq` (string) for a single value or `$in` (array of strings) for multiple values.

### Example Usage

To filter for recruits who are male and homeowners:
```json
{
  "single_select--gender": {
    "$eq": "male"
  },
  "single_select--home_owner": {
    "$eq": "homeowner"
  }
}
```

To filter for recruits in the tech or finance industry, who have a Bachelor's or Master's degree:
```json
{
  "single_select--industry": {
    "$in": ["tech", "finance"]
  },
  "single_select--level_of_education": {
    "$in": ["bachelor's", "master's"]
  }
}
```
```

--------------------------------

### Create Recruit

Source: https://api-docs.userinterviews.com/reference/post_api-recruits

Creates a new recruit on User Interviews, initiating participant recruitment. You can specify various consumer and professional criteria to qualify participants.

```APIDOC
## POST /api/recruits

### Description
Creates a new Recruit on User Interviews. This will create a new project in User Interviews and start recruiting participants to your platform.

Currently all Recruits are expected to pass a task URL that qualified participants will be directed to in order to complete an unmoderated task.

Finally, criteria can be passed to set which participants should be qualified. Currently we support the following criteria slugs:

Consumer criteria:
* `integer--age`
* `multi_select--children`
* `single_select--country`
* `multi_select--disabilities`
* `single_select--english_language_proficiency_-_speaking`
* `single_select--gender`
* `multi_select--health_insurance_type_s`
* `single_select--home_owner`
* `single_select--household_income_in_usd`
* `single_select--level_of_education`
* `single_select--living_situation`
* `single_select--locality`
* `single_select--marital_status`
* `single_select--neighborhood_type`
* `multi_select--other_language_s_spoken_fluently`
* `multi_select--pets_owned`
* `single_select_with_other--race_ethnicity`
* `single_select--region`
* `multi_select--employment_status`
* `multi_select--gig_or_contract_occupation_s`
* `single_select--military_service_status`
* `multi_select--assistive_technologies_and_custom_settings`
* `multi_select--browsers`
* `multi_select--computer_operating_system`
* `single_select--computer_with_a_webcam`
* `multi_select--smartphone_operating_system`
* `multi_select--tablet_operating_system`
* `multi_select--digital_design_prototyping_tools`
* `multi_select--food_delivery_services`
* `multi_select--health_and_wellness_apps_platforms`
* `multi_select--online_banking_financial_management_tools`
* `multi_select--online_learning_educational_platforms`
* `multi_select--online_marketplace_platforms`
* `multi_select--online_streaming_services`
* `multi_select--online_travel_booking_services`
* `multi_select--productivity_project_management_software`
* `multi_select--smart_home_and_gaming_devices`
* `multi_select--social_networking_platforms`
* `multi_select--traditional_banks`
* `multi_select--vehicles_currently_owned_or_leased`

Professional criteria:
* `single_select--occupation`
* `single_select--occupation_group`
* `multi_select--skill`
* `single_select--company_size`
* `single_select--industry`
* `single_select--seniority`
* `single_select--small_business_owner`
* `multi_select--type_of_income`
* `single_select--work_setting`

NOTE: Recruits created with the professional criteria will be charged at the B2B price.

### Method
POST

### Endpoint
/api/recruits

### Parameters
#### Request Body
- **data** (object) - Required - The recruit data.
  - **type** (string) - Required - The type of the recruit, should be "recruits".
  - **attributes** (object) - Required - The attributes of the recruit.
    - **internalName** (string) - Required - The internal name for the recruit.
    - **publicTitle** (string) - Required - The title of the recruit that participants will see.
    - **taskUrl** (string) - Required - The URL of the task that participants will complete.
    - **compensationAmount** (number) - Optional - How much each participant should be paid upon completion.
    - **deadline** (string) - Optional - The deadline for the recruit in ISO 8601 format.
    - **screener** (object) - Optional - The screener for the recruit.
      - **questions** (array) - Required - The questions for the screener.
        - **id** (string) - Required - The ID of the question.
        - **type** (string) - Required - The type of the question (e.g., "single_select", "multi_select", "open_ended").
        - **prompt** (string) - Required - The prompt for the question.
        - **options** (array) - Optional - The options for the question (for select types).
          - **value** (string) - Required - The value of the option.
          - **label** (string) - Required - The label of the option.
    - **criteria** (object) - Optional - The criteria for qualifying participants.
      - **consumer** (object) - Optional - Consumer-related criteria.
        - **integer--age** (array) - Optional - Array of integers representing age ranges.
        - **multi_select--children** (array) - Optional - Array of strings representing children options.
        - **single_select--country** (string) - Optional - Country code.
        - **multi_select--disabilities** (array) - Optional - Array of strings representing disabilities options.
        - **single_select--english_language_proficiency_-_speaking** (string) - Optional - English proficiency level.
        - **single_select--gender** (string) - Optional - Gender option.
        - **multi_select--health_insurance_type_s** (array) - Optional - Array of strings representing health insurance types.
        - **single_select--home_owner** (string) - Optional - Home owner status.
        - **single_select--household_income_in_usd** (string) - Optional - Household income range.
        - **single_select--level_of_education** (string) - Optional - Education level.
        - **single_select--living_situation** (string) - Optional - Living situation.
        - **single_select--locality** (string) - Optional - Locality.
        - **single_select--marital_status** (string) - Optional - Marital status.
        - **single_select--neighborhood_type** (string) - Optional - Neighborhood type.
        - **multi_select--other_language_s_spoken_fluently** (array) - Optional - Array of strings for other languages spoken.
        - **multi_select--pets_owned** (array) - Optional - Array of strings for pets owned.
        - **single_select_with_other--race_ethnicity** (string) - Optional - Race/ethnicity option.
        - **single_select--region** (string) - Optional - Region.
        - **multi_select--employment_status** (array) - Optional - Array of strings for employment status.
        - **multi_select--gig_or_contract_occupation_s** (array) - Optional - Array of strings for gig/contract occupations.
        - **single_select--military_service_status** (string) - Optional - Military service status.
        - **multi_select--assistive_technologies_and_custom_settings** (array) - Optional - Array of strings for assistive technologies.
        - **multi_select--browsers** (array) - Optional - Array of strings for browsers.
        - **multi_select--computer_operating_system** (array) - Optional - Array of strings for computer OS.
        - **single_select--computer_with_a_webcam** (string) - Optional - Webcam availability.
        - **multi_select--smartphone_operating_system** (array) - Optional - Array of strings for smartphone OS.
        - **multi_select--tablet_operating_system** (array) - Optional - Array of strings for tablet OS.
        - **multi_select--digital_design_prototyping_tools** (array) - Optional - Array of strings for digital design tools.
        - **multi_select--food_delivery_services** (array) - Optional - Array of strings for food delivery services.
        - **multi_select--health_and_wellness_apps_platforms** (array) - Optional - Array of strings for health apps.
        - **multi_select--online_banking_financial_management_tools** (array) - Optional - Array of strings for banking tools.
        - **multi_select--online_learning_educational_platforms** (array) - Optional - Array of strings for online learning platforms.
        - **multi_select--online_marketplace_platforms** (array) - Optional - Array of strings for online marketplace platforms.
        - **multi_select--online_streaming_services** (array) - Optional - Array of strings for streaming services.
        - **multi_select--online_travel_booking_services** (array) - Optional - Array of strings for travel booking services.
        - **multi_select--productivity_project_management_software** (array) - Optional - Array of strings for productivity software.
        - **multi_select--smart_home_and_gaming_devices** (array) - Optional - Array of strings for smart home/gaming devices.
        - **multi_select--social_networking_platforms** (array) - Optional - Array of strings for social networks.
        - **multi_select--traditional_banks** (array) - Optional - Array of strings for traditional banks.
        - **multi_select--vehicles_currently_owned_or_leased** (array) - Optional - Array of strings for vehicles owned.
      - **professional** (object) - Optional - Professional-related criteria.
        - **single_select--occupation** (string) - Optional - Occupation.
        - **single_select--occupation_group** (string) - Optional - Occupation group.
        - **multi_select--skill** (array) - Optional - Array of strings for skills.
        - **single_select--company_size** (string) - Optional - Company size.
        - **single_select--industry** (string) - Optional - Industry.
        - **single_select--seniority** (string) - Optional - Seniority level.
        - **single_select--small_business_owner** (string) - Optional - Small business owner status.
        - **multi_select--type_of_income** (array) - Optional - Array of strings for income types.
        - **single_select--work_setting** (string) - Optional - Work setting.

### Request Example
```json
{
  "data": {
    "type": "recruits",
    "attributes": {
      "internalName": "My First Recruit",
      "publicTitle": "Test Participants Needed for New App",
      "taskUrl": "https://example.com/task",
      "compensationAmount": 50,
      "deadline": "2024-12-31T23:59:59Z",
      "screener": {
        "questions": [
          {
            "id": "q1",
            "type": "single_select",
            "prompt": "What is your favorite color?",
            "options": [
              {"value": "red", "label": "Red"},
              {"value": "blue", "label": "Blue"}
            ]
          }
        ]
      },
      "criteria": {
        "consumer": {
          "integer--age": [25, 35],
          "single_select--country": "US"
        },
        "professional": {
          "single_select--industry": "Technology"
        }
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The created recruit object.
  - **id** (string) - The unique identifier for the recruit.
  - **type** (string) - The type of the object, always "recruits".
  - **attributes** (object) - The attributes of the recruit.
    - **createdAt** (string) - The date and time the recruit was created.
    - **internalName** (string) - The internal name for the recruit.
    - **publicTitle** (string) - The title of the recruit that participants will see.
    - **status** (string) - The current status of the recruit (e.g., "draft", "active", "completed").
    - **compensationAmount** (number) - How much each participant should be paid upon completion.
    - **deadline** (string) - The deadline for the recruit.
  - **links** (object) - Links related to the recruit.
    - **self** (string) - The URL to the recruit.

#### Response Example
```json
{
  "data": {
    "id": "rec_12345",
    "type": "recruits",
    "attributes": {
      "createdAt": "2023-10-27T10:00:00Z",
      "internalName": "My First Recruit",
      "publicTitle": "Test Participants Needed for New App",
      "status": "draft",
      "compensationAmount": 50,
      "deadline": "2024-12-31T23:59:59Z"
    },
    "links": {
      "self": "https://user-interviews.com/recruits/rec_12345"
    }
  }
}
```
```

--------------------------------

### Get a specific participant

Source: https://api-docs.userinterviews.com/reference/get_api-recruits-recruit-id-participants-participant-id-1

Fetches a participant's details using their ID and the recruit's ID.

```APIDOC
## GET /api/recruits/{recruit_id}/participants/{participant_id}

### Description
Retrieves a specific participant within a recruit.

### Method
GET

### Endpoint
/api/recruits/{recruit_id}/participants/{participant_id}

### Parameters
#### Path Parameters
- **recruit_id** (string) - Required - The unique identifier for the recruit.
- **participant_id** (string) - Required - The unique identifier for the participant.

### Response
#### Success Response (200)
- **data** (object) - Contains the participant's data.
  - **id** (string) - The participant's unique identifier.
  - **type** (string) - The type of the resource, typically "participants".
  - **attributes** (object) - Contains the participant's attributes.
  - **links** (object) - Contains links related to the participant.

#### Response Example
```json
{
  "data": {
    "id": "participant_id_123",
    "type": "participants",
    "attributes": {
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    "links": {
      "self": "/api/recruits/recruit_id_456/participants/participant_id_123"
    }
  }
}
```

#### Error Response (401)
- **description**: Unauthorized

#### Error Response (404)
- **description**: participant not found
```

--------------------------------

### Authenticate Request with API Key

Source: https://api-docs.userinterviews.com/reference/authentication

Include your API key in the 'user-interviews-apikey' header for authenticated requests. Replace 'APIKEY' with your actual key.

```shell
-H "user-interviews-apikey: APIKEY"
```