# BlockSurvey Rest API

### Overview

The BlockSurvey API offers you the power to efficiently interact with the BlockSurvey platform programmatically. It opens a vast spectrum of possibilities, allowing you to retrieve, update, and manage data related to your surveys and responses. This API is designed with a strong focus on simplicity and robustness, making it easy to integrate BlockSurvey into your own applications, systems, or workflows.

Whether you aim to automate survey dissemination, aggregate response data for analysis, or integrate BlockSurvey into your existing business systems, our API provides the tools to make it happen. This documentation serves as a comprehensive guide, outlining detailed information on available endpoints, request/response structures, authentication processes, and more.

### Coming Soon

While the BlockSurvey API currently provides powerful capabilities to access, modify, and manage your survey data, our commitment to continuous improvement means there's always more on the horizon. We're constantly working on expanding our API's functionality to offer more flexibility and enable more complex use cases.

In the coming months, we'll be releasing new endpoints and features, enhancing the scope of our API to further meet your needs. These enhancements will include, but are not limited to:

1. **Advanced-Data Filtering:** We're developing methods to give you even more control over how you fetch and view your data.
2. **Bulk Operations:** Soon, you'll be able to handle multiple surveys or responses at once, saving time and reducing complexity.
3. **Webhook Integrations:** We're working to allow your application to listen to events happening in real time within BlockSurvey, opening up new possibilities for automation and integration.

Stay tuned to this space for updates on these exciting new features and others as we continue to evolve the BlockSurvey API to better serve you.

Empower your application with BlockSurvey today, and unlock a new dimension of survey management at your fingertips.


# Authentication

BlockSurvey enables your application to secure the authorization to connect with its platform using OAuth 2.0 authentication method. Here's how you can generate an API key:

### Prerequisites

You need to have a BlockSurvey account. If you don't have one, please sign up.

### Steps to Generate an API Key

1. Sign in to your BlockSurvey account.
2. Navigate to `Settings → Organization Settings → Configuration & API Configuration`.
3. Click on `Generate New API Key`.
4. Enter a name for the API Key and click `Save`.Your new API key will be displayed.&#x20;

**Make sure to copy this key and keep it in a safe place. The API Key will only be displayed once and you will need to regenerate it if you lose it.**

### Using the API Key for Authentication

Each API request requires an `Authorization` header with your API key.\
\
**cURL Example**

```bash
curl --request GET \
 --url 'https://api3.blocksurvey.io' \
 --header  'Authorization: Bearer user_api_token'
```

Remember to replace `user_api_token` in the cURL example with the actual API Key when testing or using the API endpoint.<br>


# Response Codes

BlockSurvey uses standard HTTP status codes like 2xx for success and 4xx and 5xx for failure. Refer to the following table for status codes.\
\
**Response Codes and Descriptions**

<table><thead><tr><th width="292">Status Code</th><th>Description</th></tr></thead><tbody><tr><td>200 OK</td><td>The request has succeeded.</td></tr><tr><td>400 Bad Request</td><td>The request has missing required parameters or validation errors.</td></tr><tr><td>401 Unauthorized</td><td>The request has not been applied because it lacks valid authentication credentials for the target resource.</td></tr><tr><td>403 Forbidden</td><td>Correct API key provided but the user doesn't have the team role/permission.</td></tr><tr><td>404 Not Found</td><td>The requested resource doesn’t exist.</td></tr><tr><td>429 Too Many Requests</td><td>The user has sent too many requests in a given amount of time.</td></tr><tr><td>500 Internal Server Error</td><td>The server encountered an unexpected condition that prevented it from fulfilling the request.</td></tr></tbody></table>


# Get a survey cut off date

### Overview

This endpoint returns the cut-off date for a specific survey.

### Authentication

This request requires an `Authorization` header with a valid token.<br>

**URL:** `GET https://api3.blocksurvey.io/v1/survey/cut_off_date`

**Query Parameters**

| Parameter | Type   | Optional | Description           |
| --------- | ------ | -------- | --------------------- |
| surveyId  | String | No       | The ID of the survey. |
| teamId    | String | Yes      | The team ID.          |

### **cURL Example**

```bash
curl --request GET \
 --url 'https://api3.blocksurvey.io/v1/survey/cut_off_date?surveyId=YOUR_SURVEY_ID&teamId=YOUR_TEAM_ID' \
 --header  'Authorization: Bearer user_api_token'
```

Remember to replace `YOUR_SURVEY_ID` and `YOUR_TEAM_ID` in the cURL example with actual values when testing or using the API endpoint.

### **Response**

**Successful Response**

```json
{
  "status": "success",
  "scheduledStartDate": 1655702822000
}
```


# Get a survey scheduled start date

### Overview

This endpoint returns the scheduled start date for a specific survey.

### Authentication

This request requires an `Authorization` header with a valid token.<br>

**URL:** `GET https://api3.blocksurvey.io/v1/survey/scheduled_start_date`<br>

**Query Parameters**

| Parameter | Type   | Optional | Description           |
| --------- | ------ | -------- | --------------------- |
| surveyId  | String | No       | The ID of the survey. |
| teamId    | String | Yes      | The team ID.          |

### **cURL Example**

```bash
curl --request GET \
 --url 'https://api3.blocksurvey.io/v1/survey/scheduled_start_date?surveyId=YOUR_SURVEY_ID&teamId=YOUR_TEAM_ID' \
 --header  'Authorization: Bearer user_api_token'
```

Remember to replace `YOUR_SURVEY_ID` and `YOUR_TEAM_ID` in the cURL example with actual values when testing or using the API endpoint.

### **Response**

**Successful Response**

```json
{
  "status": "success",
  "scheduledStartDate": 1655702822000
}
```


# Get a survey limit maximum response count

### Overview

This endpoint returns the maximum response count limit for a specific survey.

### Authentication

This request requires an `Authorization` header with a valid token.\
\
**URL:** `GET https://api3.blocksurvey.io/v1/survey/limit_maximum_response_count`

\
**Query Parameters**

| Parameter | Type   | Optional | Description           |
| --------- | ------ | -------- | --------------------- |
| surveyId  | String | No       | The ID of the survey. |
| teamId    | String | Yes      | The team ID.          |

### **cURL Example**

```bash
curl --request GET \
 --url 'https://api3.blocksurvey.io/v1/survey/limit_maximum_response_count?surveyId=YOUR_SURVEY_ID&teamId=YOUR_TEAM_ID' \
 --header  'Authorization: Bearer user_api_token'
```

Remember to replace `YOUR_SURVEY_ID` and `YOUR_TEAM_ID` in the cURL example with actual values when testing or using the API endpoint.

### **Response**

**Successful Response**

```json
{
  "status": "success",
  "limitMaximumResponseCount": 100
}
```


# Get a survey text variable value

### Overview

This endpoint retrieves a text variable value for a specific survey.

### Authentication

This request requires an Authorization header with a valid token.

\
**URL:** `GET https://api3.blocksurvey.io/v1/survey/text_variable_value`

\
**Query Parameters**

| Parameter        | Type   | Optional | Description                    |
| ---------------- | ------ | -------- | ------------------------------ |
| surveyId         | String | No       | The ID of the survey.          |
| textVariableName | String | No       | The name of the text variable. |
| teamId           | String | Yes      | The team ID.                   |

### **cURL Example**

```bash
curl --request GET \
 --url 'https://api3.blocksurvey.io/v1/survey/text_variable_value?surveyId=YOUR_SURVEY_ID&textVariableName=YOUR_TEXT_VARIABLE_NAME&teamId=YOUR_TEAM_ID' \
 --header  'Authorization: Bearer user_api_token'
```

Remember to replace `YOUR_SURVEY_ID`, `YOUR_TEXT_VARIABLE_NAME`, and `YOUR_TEAM_ID` with actual values when testing or using this API endpoint.

### Response

**Successful Response**

```json
{
  "status": "success",
  "textVariableValue": "abc"
}
```


# Update a survey cut off date

### Overview

This endpoint updates the cut-off date for a specific survey.

### Authentication

This request requires an `Authorization` header with a valid token.\
\
**URL:** `POST https://api3.blocksurvey.io/v1/survey/cut_off_date`

\
**Body Parameters**

| Parameter      | Type    | Optional | Description                                |
| -------------- | ------- | -------- | ------------------------------------------ |
| surveyId       | String  | No       | The ID of the survey.                      |
| cutOffDateFlag | Boolean | No       | Flag to set the cut-off date (true/false). |
| cutOffDate     | Number  | No       | The cut-off date in timestamp format.      |
| teamId         | String  | Yes      | The team ID.                               |

Here's the JSON body data:

```json
{
    "surveyId": "123456",
    "teamId": "1234",
    "cutOffDateFlag": true,
    "cutOffDate": 1677619200000
}
```

### **cURL Example**

```bash
curl --request POST \
 --url 'https://api3.blocksurvey.io/v1/survey/cut_off_date' \
 --header  'Authorization: Bearer user_api_token' \
 --header 'Content-Type: application/json' \
 --data '{
    "surveyId": "YOUR_SURVEY_ID",
    "cutOffDateFlag": true/false,
    "cutOffDate": TIMESTAMP,
    "teamId": "YOUR_TEAM_ID"
 }'
```

Remember to replace `YOUR_SURVEY_ID`, `TIMESTAMP`, and `YOUR_TEAM_ID` with actual values when testing or using this API endpoint. The `cutOffDateFlag` should be either `true` or `false`.

### **Response**

**Successful Response**

```json
{
  "status": "success",
  "message": "Survey cut off date updated successfully."
}
```


# Update a survey scheduled start date

### Overview

This endpoint updates the scheduled start date for a specific survey.

### Authentication

This request requires an Authorization header with a valid token.

\
**URL:** `POST https://api3.blocksurvey.io/v1/survey/scheduled_start_date`

\
**Body Parameters**

| Parameter              | Type    | Optional | Description                                        |
| ---------------------- | ------- | -------- | -------------------------------------------------- |
| surveyId               | String  | No       | The ID of the survey.                              |
| scheduledStartDateFlag | Boolean | No       | Flag to set the scheduled start date (true/false). |
| scheduledStartDate     | Number  | No       | The scheduled start date in timestamp format.      |
| teamId                 | String  | Yes      | The team ID.                                       |

Here's the JSON body data:

```json
{
    "surveyId": "123456",
    "teamId": "1234",
    "scheduledStartDateFlag": true,
    "scheduledStartDate": 1677619200000
}
```

### **cURL Example**

```bash
curl --request POST \
 --url 'https://api3.blocksurvey.io/v1/survey/scheduled_start_date' \
 --header  'Authorization: Bearer user_api_token' \
 --header 'Content-Type: application/json' \
 --data '{
    "surveyId": "YOUR_SURVEY_ID",
    "scheduledStartDateFlag": true/false,
    "scheduledStartDate": TIMESTAMP,
    "teamId": "YOUR_TEAM_ID"
 }'
```

Remember to replace `YOUR_SURVEY_ID`, `TIMESTAMP`, and `YOUR_TEAM_ID` with actual values when testing or using this API endpoint. The `scheduledStartDateFlag` should be either `true` or `false`.

### Response

**Successful Response**

```json
{
  "status": "success",
  "message": "Survey scheduled start date updated successfully."
}
```


# Update a survey limit maximum response count

### Overview

This endpoint updates the limit maximum response count for a specific survey.

### Authentication

This request requires an Authorization header with a valid token.<br>

**URL:** `POST https://api3.blocksurvey.io/v1/survey/limit_maximum_response_count`

\
**Body Parameters**

| Parameter                     | Type    | Optional | Description                                                |
| ----------------------------- | ------- | -------- | ---------------------------------------------------------- |
| surveyId                      | String  | No       | The ID of the survey.                                      |
| limitMaximumResponseCountFlag | Boolean | No       | Flag to set the limit maximum response count (true/false). |
| limitMaximumResponseCount     | Number  | No       | The limit maximum response count.                          |
| teamId                        | String  | Yes      | The team ID.                                               |

Here's the JSON body data:

```json
{
    "surveyId": "123456",
    "teamId": "1234",
    "limitMaximumResponseCountFlag": true,
    "limitMaximumResponseCount": 100
}
```

### **cURL Example**

```bash
curl --request POST \
 --url 'https://api3.blocksurvey.io/v1/survey/limit_maximum_response_count' \
 --header  'Authorization: Bearer user_api_token' \
 --header 'Content-Type: application/json' \
 --data '{
    "surveyId": "YOUR_SURVEY_ID",
    "limitMaximumResponseCountFlag": true/false,
    "limitMaximumResponseCount": NUMBER,
    "teamId": "YOUR_TEAM_ID"
 }'
```

Remember to replace `YOUR_SURVEY_ID`, `NUMBER`, and `YOUR_TEAM_ID` with actual values when testing or using this API endpoint. The `limitMaximumResponseCountFlag` should be either `true` or `false`.

### Response

**Successful Response**

```json
{
  "status": "success",
  "message": "Survey limit maximum response count updated successfully."
}
```


# Update a survey text variable value

### Overview

This endpoint updates a text variable value for a specific survey.

### Authentication

This request requires an Authorization header with a valid token.

\
**URL:** `POST https://api3.blocksurvey.io/v1/survey/text_variable_value`

\
**Body Parameters**

| Parameter         | Type    | Optional | Description                                                                  |
| ----------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| surveyId          | String  | No       | The ID of the survey.                                                        |
| textVariableFlag  | Boolean | No       | Flag to set the text variable (true for insert/update and false for delete). |
| textVariableName  | String  | No       | The name of the text variable.                                               |
| textVariableValue | String  | Yes      | The value of the text variable.                                              |
| teamId            | String  | Yes      | The team ID.                                                                 |

Here's the JSON body data:

```json
{
    "surveyId": "123456",
    "teamId": "1234",
    "textVariableFlag": true,
    "textVariableName": "ref",
    "textVariableValue": "xyz"
}
```

### **cURL Example**

```bash
curl --request POST \
 --url 'https://api3.blocksurvey.io/v1/survey/text_variable_value' \
 --header  'Authorization: Bearer user_api_token' \
 --header 'Content-Type: application/json' \
 --data '{
    "surveyId": "YOUR_SURVEY_ID",
    "textVariableFlag": true/false,
    "textVariableName": "YOUR_TEXT_VARIABLE_NAME",
    "textVariableValue": "YOUR_TEXT_VARIABLE_VALUE",
    "teamId": "YOUR_TEAM_ID"
 }'
```

Remember to replace `YOUR_SURVEY_ID`, `YOUR_TEXT_VARIABLE_NAME`, `YOUR_TEXT_VARIABLE_VALUE`, and `YOUR_TEAM_ID` with actual values when testing or using this API endpoint. The `textVariableFlag` should be either `true` or `false`.

### Response

**Successful Response**

```json
{
  "status": "success",
  "message": "Survey text variable updated successfully."
}
```


# Contact List Metadata

Before creating a contact in BlockSurvey, you must locate the **Team ID**, **List ID**, **List Public Key**, and **List Private Key**. These identifiers are essential for managing contacts via BlockSurvey’s APIs.

Steps to locate the metadata:

1. Log in to **BlockSurvey** and navigate to your **Teamspace**.<br>
2. Go to the **Audience** menu.<br>
3. Click **Create Audience List**, enter a name, and click **Create**.<br>
4. Once the list is created, click **Create Contact** to manually add contacts.<br>
5. Click on **Dev Console** to open a popup displaying the metadata needed to manage your contacts via the API.

<figure><img src="https://317786790-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuQeHI9Ynv4VNgBLNIcHJ%2Fuploads%2FLtzT1wzU0TNBhR2wkHMh%2F2025-03-28%2018_17_06-.png?alt=media&amp;token=e35615c9-efc9-4e3c-99e7-c563627374a0" alt=""><figcaption></figcaption></figure>

Metadata Information:

* **Team ID** – A Unique identifier for your team.<br>
* **List ID** – Identifier for the selected contact list.<br>
* **List Public Key** – Used for encrypting data when adding contacts.<br>
* **List Private Key** – Used for decrypting data when required.

Once you have these details, you can proceed with the API integration to manage your contacts efficiently.<br>


# Create Contact

### **Overview**

Creates a new contact in a specified list.

### Authentication <a href="#authentication" id="authentication"></a>

This request requires a `Authorization` header with a valid token.&#x20;

**URL:** `POST https://api3.blocksurvey.io/contact/create-contact`

### Request Headers

| Key           | Value              | Description                 |
| ------------- | ------------------ | --------------------------- |
| Authorization | Bearer \<api\_key> | API key for authentication. |

### Request Body

| Field                                                              | Type   | Required | Description                        |
| ------------------------------------------------------------------ | ------ | -------- | ---------------------------------- |
| teamId                                                             | String | Yes      | ID of the team owning the list.    |
| listId                                                             | String | Yes      | ID of the list to add the contact. |
| listPublicKey                                                      | String | Yes      | Public key for encryption.         |
| Email                                                              | String | Yes      | Email address of the contact.      |
| <p>First Name</p><p>Last Name</p><p>Phone Number</p><p>Country</p> | String | No       | Additional column data.            |

### cURL Example

```bash
curl -X POST https://api3.blocksurvey.io/contact/create-contact
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
    "teamId": "team-123",
    "listId": "list-456",
    "listPublicKey": "base64-public-key",
    "Email": "example@example.com",
    "First Name": "John",
    "Last Name": "Doe"
}'

```

### Response

**Successful Response**

```json
{
    "success": true,
    "recordId": "contact-id"
}
```

### Errors

| Error Message | Status Code             | Description                        |
| ------------- | ----------------------- | ---------------------------------- |
| 400           | Missing required fields | Required fields are missing.       |
| 401           | Unauthorized            | Invalid or missing API key.        |
| 404           | List not found          | The specified list does not exist. |
| 409           | Contact already exists  | The contact already exists.        |
| 500           | Internal server error   | An unexpected error occurred.      |


# Update Contact

### **Overview**

Updates an existing contact in a specified list.

### Authentication

This request requires a `Authorization` header with a valid token.&#x20;

**URL:** `PUT https://api3.blocksurvey.io/contact/update-contact`

### Request Headers

| Key           | Value              | Description                 |
| ------------- | ------------------ | --------------------------- |
| Authorization | Bearer \<api\_key> | API key for authentication. |

### Request Body

| Field                                                              | Type   | Required | Description                                                             |
| ------------------------------------------------------------------ | ------ | -------- | ----------------------------------------------------------------------- |
| teamId                                                             | String | Yes      | ID of the team owning the list.                                         |
| listId                                                             | String | Yes      | ID of the list containing contact.                                      |
| listPublicKey                                                      | String | Yes      | Public key for encryption.                                              |
| recordId                                                           | String | No       | ID of the contact to update. Required if oldEmail is not provided.      |
| oldEmail                                                           | String | No       | Old email of the contact. Required if recordId is not provided.         |
| Email                                                              | String | No       | New email of the contact. If provided, oldEmail must also be included.. |
| <p>First Name</p><p>Last Name</p><p>Phone Number</p><p>Country</p> | String | No       | Additional column data.                                                 |

### cURL Example

```bash
curl -X PUT https://api3.blocksurvey.io/contact/update-contact
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
    "teamId": "team-123",
    "listId": "list-456",
    "listPublicKey": "base64-public-key",
    "recordId": "contact-789",
    "oldEmail": "old-email@example.com",
    "Email": "new-email@example.com",
    "First Name": "Jane"
}'
```

### Response

**Successful Response**

```json
Success (200)
{
    "success": true,
    "recordId": "contact-id"
}
```

<br>


# Get Contact

### **Overview**

Retrieves details of an existing contact from a specified list.

### Authentication

This request requires a `Authorization` header with a valid token.&#x20;

**URL:** `POST https://api3.blocksurvey.io/contact/get-contact`

### Request Body

| Field          | Type   | Required | Description                                                                |
| -------------- | ------ | -------- | -------------------------------------------------------------------------- |
| teamId         | String | Yes      | ID of the team owning the list.                                            |
| listId         | String | Yes      | ID of the list containing contact.                                         |
| listPrivateKey | String | Yes      | Private key for decryption.                                                |
| recordId       | String | No       | ID of the contact to retrieve or update (optional).                        |
| Email          | String | No       | Email of the contact (optional), but required if recordId is not provided. |

### cURL Example

```bash
curl -X GET https://api3.blocksurvey.io/contact/get-contact
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
    "teamId": "team-123",
    "listId": "list-456",
    "listPrivateKey": "base64-private-key",
    "Email": "example@example.com"
}'
```

### Response

**Successful Response**

```json
Success (200)
{
    "success": true,
    "contactDetails": 
    {
       "Email": "example@example.com",
       “First Name”:  “John”,
       “Last Name”: “Doe”,
       “Phone Number”: “123 456 789 0”,
       “Country”: “US”   
       }
}
```


# Delete Contact

### **Overview**

Deletes an existing contact from a specified list.

### Authentication

This request requires a `Authorization` header with a valid token.&#x20;

**URL:** `DELETE https://api3.blocksurvey.io/contact/delete-contact`

### Request Body

| Field    | Type   | Required | Description                                                                |
| -------- | ------ | -------- | -------------------------------------------------------------------------- |
| teamId   | String | Yes      | ID of the team owning the list.                                            |
| listId   | String | Yes      | ID of the list containing contact.                                         |
| recordId | String | No       | ID of the contact to delete.                                               |
| Email    | String | No       | Email of the contact (optional), but required if recordId is not provided. |

### cURL Example

```bash
curl -X DELETE  https://api3.blocksurvey.io/contact/delete-contact
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
    "teamId": "team-123",
    "listId": "list-456",
    "recordId": "contact-789",
    "Email": "new-email@example.com",

}'
```

### Response

**Successful Response**

```json
Success (200)
{
    "success": true,
    "message": "Contact deleted successfully."
}
```
Status Code	Description
200 OK	The request has succeeded.
400 Bad Request	The request has missing required parameters or validation errors.
401 Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource.
403 Forbidden	Correct API key provided but the user doesn't have the team role/permission.
404 Not Found	The requested resource doesn’t exist.
429 Too Many Requests	The user has sent too many requests in a given amount of time.
500 Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.