# Export demographic data

POST https://api.prolific.com/api/v1/studies/{id}/demographic-export/
Content-Type: application/json

Create and download a demographic export for a study. This endpoint allows you to export participant demographic data with optional study filter data.

**Filter Support**: This endpoint supports applying demographic filters to export data for participants who match specific criteria.

When filters are provided, the export includes both base demographic data (age, sex, country, etc.) and the filters.

When no filters are provided, the export includes only base demographic data for all participants who took the study, excluding any study-specific filter responses.

**Export Usage**: Please note that you may only select up to 15 filters per export. You are also limited to 2 different filter export requests.

You may download the same request as many times as you need. To check your current usage and see your latest export history, use the [Demographic Export History](https://docs.prolific.com/docs/api-docs/public/#tag/Studies/operation/GetDemographicExportHistory) endpoint.

**Basic Data Included**: The export includes the following data fields:
* Submission ID
* Participant ID
* Submission status
* Started date-time
  * Expressed in UTC
  * ISO 8601 formatted
* Completed date-time
  * Expressed in UTC
  * ISO 8601 formatted
* Time taken (in seconds)
* Age
* Sex
  * Participants were asked the following question: What is your sex, as recorded on legal/official documents?
* First language
* Current country of residence
* Nationality
* Country of birth
* Student status
* Employment status
* Reviewed at date-time
  * Expressed in UTC
  * ISO 8601 formatted
* Completion code ('entered code')

Learn more on [Exporting Prolific demographic data](https://researcher-help.prolific.com/en/article/b2943f).

Reference: https://beta-docs.prolific.com/api-reference/studies/export-demographic-data

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Export demographic data
  version: endpoint_studies.ExportDemographicData
paths:
  /api/v1/studies/{id}/demographic-export/:
    post:
      operationId: export-demographic-data
      summary: Export demographic data
      description: >-
        Create and download a demographic export for a study. This endpoint
        allows you to export participant demographic data with optional study
        filter data.


        **Filter Support**: This endpoint supports applying demographic filters
        to export data for participants who match specific criteria.


        When filters are provided, the export includes both base demographic
        data (age, sex, country, etc.) and the filters.


        When no filters are provided, the export includes only base demographic
        data for all participants who took the study, excluding any
        study-specific filter responses.


        **Export Usage**: Please note that you may only select up to 15 filters
        per export. You are also limited to 2 different filter export requests.


        You may download the same request as many times as you need. To check
        your current usage and see your latest export history, use the
        [Demographic Export
        History](https://docs.prolific.com/docs/api-docs/public/#tag/Studies/operation/GetDemographicExportHistory)
        endpoint.


        **Basic Data Included**: The export includes the following data fields:

        * Submission ID

        * Participant ID

        * Submission status

        * Started date-time
          * Expressed in UTC
          * ISO 8601 formatted
        * Completed date-time
          * Expressed in UTC
          * ISO 8601 formatted
        * Time taken (in seconds)

        * Age

        * Sex
          * Participants were asked the following question: What is your sex, as recorded on legal/official documents?
        * First language

        * Current country of residence

        * Nationality

        * Country of birth

        * Student status

        * Employment status

        * Reviewed at date-time
          * Expressed in UTC
          * ISO 8601 formatted
        * Completion code ('entered code')


        Learn more on [Exporting Prolific demographic
        data](https://researcher-help.prolific.com/en/article/b2943f).
      tags:
        - - subpackage_studies
      parameters:
        - name: id
          in: path
          description: Study ID
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Header authentication of the form `undefined <token>`
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Demographic data exported successfully
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DemographicExportRequest'
components:
  schemas:
    SelectFilter:
      type: object
      properties:
        filter_id:
          type: string
          description: ID of the "select" type filter.
        selected_values:
          type: array
          items:
            type: string
          description: >-
            This schema applies for filters of the `select` type, as defined in
            the [filter list
            response](\#tag/Filters/paths/~1api~1v1~1filters~1/get).


            Array of IDs matching the response IDs, from the `select` filter's
            `choices` (see response linked above).


            String format should match the `data_type` of the `select` filter's
            `choices` (see response linked above).
        weightings:
          type: object
          additionalProperties:
            type: number
            format: double
          description: >-
            Ratios to control the distribution of participants across the
            selected values.


            Integer percentages, floats, and exact quantities are valid inputs.
      required:
        - filter_id
        - selected_values
    RangeFilterSelectedRangeLower:
      oneOf:
        - type: integer
        - type: string
        - type: number
          format: double
    RangeFilterSelectedRangeUpper:
      oneOf:
        - type: integer
        - type: string
        - type: number
          format: double
    RangeFilterSelectedRange:
      type: object
      properties:
        lower:
          $ref: '#/components/schemas/RangeFilterSelectedRangeLower'
          description: Your selected lower bound for the range.
        upper:
          $ref: '#/components/schemas/RangeFilterSelectedRangeUpper'
          description: Your selected upper bound for the range.
    RangeFilterWeightingsSelectedRangeLower:
      oneOf:
        - type: integer
        - type: string
        - type: number
          format: double
    RangeFilterWeightingsSelectedRangeUpper:
      oneOf:
        - type: integer
        - type: string
        - type: number
          format: double
    RangeFilterWeightingsSelectedRange:
      type: object
      properties:
        lower:
          $ref: '#/components/schemas/RangeFilterWeightingsSelectedRangeLower'
        upper:
          $ref: '#/components/schemas/RangeFilterWeightingsSelectedRangeUpper'
    RangeFilterWeightings:
      type: object
      properties:
        selected_range:
          $ref: '#/components/schemas/RangeFilterWeightingsSelectedRange'
        weighting:
          type: number
          format: double
      required:
        - selected_range
        - weighting
    RangeFilter:
      type: object
      properties:
        filter_id:
          type: string
          description: ID of the "range" type filter.
        selected_range:
          $ref: '#/components/schemas/RangeFilterSelectedRange'
          description: >-
            This schema applies for filters of the `range` type, as defined in
            the [filter list
            response](\#tag/Filters/paths/~1api~1v1~1filters~1/get).


            A dictionary with two possible objects, 'lower' and 'upper'. At
            least one must be present and a non-null value.


            The expected data type for these values is defined by the `range`
            filter's `data_type` (see response linked above).


            If the data_type is a date, string format should be a parseable
            ISO8601 date string. Date values should be provided as a string in
            ISO 8601 format.


            Leaving a value as null will result in that bound being set to the
            lowest or highest possible value, depending on whether it is the
            upper or lower bound.
        weightings:
          $ref: '#/components/schemas/RangeFilterWeightings'
          description: >-
            Ratios to control the distribution of participants across the
            selected values.


            Integers and exact quantities are valid inputs.
      required:
        - filter_id
        - selected_range
    DemographicExportRequestFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
    DemographicExportRequest:
      type: object
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/DemographicExportRequestFiltersItems'
          description: >-
            List of filters to apply to the demographic export.


            When filters are provided, the export includes both base demographic
            data and responses to the specified filters which were applied to
            the study.


            When empty, only base demographic data (age, sex, country, etc.) for
            all participants who took the study is exported, excluding
            study-specific filter responses.

```

## SDK Code Examples

```python
import requests

url = "https://api.prolific.com/api/v1/studies/id/demographic-export/"

payload = { "filters": [] }
headers = {
    "Authorization": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript
const url = 'https://api.prolific.com/api/v1/studies/id/demographic-export/';
const options = {
  method: 'POST',
  headers: {Authorization: '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"filters":[]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prolific.com/api/v1/studies/id/demographic-export/"

	payload := strings.NewReader("{\n  \"filters\": []\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.prolific.com/api/v1/studies/id/demographic-export/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filters\": []\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.prolific.com/api/v1/studies/id/demographic-export/")
  .header("Authorization", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filters\": []\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.prolific.com/api/v1/studies/id/demographic-export/', [
  'body' => '{
  "filters": []
}',
  'headers' => [
    'Authorization' => '<apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.prolific.com/api/v1/studies/id/demographic-export/");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"filters\": []\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["filters": []] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.prolific.com/api/v1/studies/id/demographic-export/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://api.prolific.com/api/v1/studies/id/demographic-export/"

payload = { "filters": [
        {
            "filter_id": "age",
            "selected_range": {
                "lower": 25,
                "upper": 35
            }
        },
        {
            "filter_id": "sex",
            "selected_values": ["0", "1"]
        }
    ] }
headers = {
    "Authorization": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript
const url = 'https://api.prolific.com/api/v1/studies/id/demographic-export/';
const options = {
  method: 'POST',
  headers: {Authorization: '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"filters":[{"filter_id":"age","selected_range":{"lower":25,"upper":35}},{"filter_id":"sex","selected_values":["0","1"]}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prolific.com/api/v1/studies/id/demographic-export/"

	payload := strings.NewReader("{\n  \"filters\": [\n    {\n      \"filter_id\": \"age\",\n      \"selected_range\": {\n        \"lower\": 25,\n        \"upper\": 35\n      }\n    },\n    {\n      \"filter_id\": \"sex\",\n      \"selected_values\": [\n        \"0\",\n        \"1\"\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.prolific.com/api/v1/studies/id/demographic-export/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filters\": [\n    {\n      \"filter_id\": \"age\",\n      \"selected_range\": {\n        \"lower\": 25,\n        \"upper\": 35\n      }\n    },\n    {\n      \"filter_id\": \"sex\",\n      \"selected_values\": [\n        \"0\",\n        \"1\"\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.prolific.com/api/v1/studies/id/demographic-export/")
  .header("Authorization", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filters\": [\n    {\n      \"filter_id\": \"age\",\n      \"selected_range\": {\n        \"lower\": 25,\n        \"upper\": 35\n      }\n    },\n    {\n      \"filter_id\": \"sex\",\n      \"selected_values\": [\n        \"0\",\n        \"1\"\n      ]\n    }\n  ]\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.prolific.com/api/v1/studies/id/demographic-export/', [
  'body' => '{
  "filters": [
    {
      "filter_id": "age",
      "selected_range": {
        "lower": 25,
        "upper": 35
      }
    },
    {
      "filter_id": "sex",
      "selected_values": [
        "0",
        "1"
      ]
    }
  ]
}',
  'headers' => [
    'Authorization' => '<apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.prolific.com/api/v1/studies/id/demographic-export/");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"filters\": [\n    {\n      \"filter_id\": \"age\",\n      \"selected_range\": {\n        \"lower\": 25,\n        \"upper\": 35\n      }\n    },\n    {\n      \"filter_id\": \"sex\",\n      \"selected_values\": [\n        \"0\",\n        \"1\"\n      ]\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["filters": [
    [
      "filter_id": "age",
      "selected_range": [
        "lower": 25,
        "upper": 35
      ]
    ],
    [
      "filter_id": "sex",
      "selected_values": ["0", "1"]
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.prolific.com/api/v1/studies/id/demographic-export/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```