> For the complete documentation index, see [llms.txt](https://manual.blocworx.com/blocworx-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manual.blocworx.com/blocworx-api/reference/api-reference/updating-data.md).

# Updating Data

### Update Records by Matching Field Values

This endpoint updates one or more records in a bloc by matching exact field-value pairs.

<mark style="color:green;">`POST`</mark> `https://example.mydomain.com/api/update-records-by-matching-values`

***

### Request Body

<table><thead><tr><th width="176.29296875">Name</th><th width="122.98828125">Type</th><th>Description</th></tr></thead><tbody><tr><td>blocId<mark style="color:red;">*</mark></td><td>string</td><td>The ID of the bloc to update. This may be a UUID or numeric ID depending on your instance.</td></tr><tr><td>fieldsToUpdate<mark style="color:red;">*</mark></td><td>object</td><td>Field slugs and the values to apply to matching records. Example: <code>{ "employee_name": "Jane Doe", "status": "Complete" }</code></td></tr><tr><td>searchItems<mark style="color:red;">*</mark></td><td>object</td><td>Field slugs and exact values used to find records to update. Example: <code>{ "employee_id": "5830" }</code></td></tr></tbody></table>

***

### Matching Behavior

* Matching uses exact key/value equality
* All matching records are updated
* If no records match, the request still succeeds and returns an empty array of updated IDs

***

### 200 Success Response

#### Records Updated

```json
{
  "updated_record_ids": [
    1223259
  ]
}
```

#### No Matching Records

```json
{
  "updated_record_ids": []
}
```

***

### Error Responses

#### 400 Bad Request

Returned when required request fields are missing.

```json
{
  "error": "Search Key/Value pairs or Bloc ID or Search Fields to update have not been provided"
}
```

Additional validation failures may return a `message` field instead of `error`, depending on the failure path.

#### 401 Unauthorized

```json
{
  "message": "You are not authorized to access this bloc"
}
```

***

### Example Requests

#### cURL

```bash
curl --request POST 'https://example.mydomain.com/api/update-records-by-matching-values' \
  --header 'Authorization: Bearer [AUTHTOKEN]' \
  --header 'Content-Type: application/json' \
  --data '{
    "blocId": "a1489634-4009-4cc0-8a65-9965f5a1bea7",
    "fieldsToUpdate": {
      "field_number_2": "Updated Value"
    },
    "searchItems": {
      "field_number_1": "Rafael"
    }
  }'
```

#### JavaScript

```javascript
const settings = {
  url: 'https://example.mydomain.com/api/update-records-by-matching-values',
  method: 'POST',
  timeout: 0,
  headers: {
    Authorization: 'Bearer [AUTHTOKEN]',
    'Content-Type': 'application/json'
  },
  data: JSON.stringify({
    blocId: 'a1489634-4009-4cc0-8a65-9965f5a1bea7',
    fieldsToUpdate: {
      field_number_2: 'Updated Value'
    },
    searchItems: {
      field_number_1: 'Rafael'
    }
  })
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
```

#### Node.js

```javascript
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://example.mydomain.com/api/update-records-by-matching-values',
  headers: {
    Authorization: 'Bearer [AUTHTOKEN]',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    blocId: 'a1489634-4009-4cc0-8a65-9965f5a1bea7',
    fieldsToUpdate: {
      field_number_2: 'Updated Value'
    },
    searchItems: {
      field_number_1: 'Rafael'
    }
  })
};

request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

#### Python

```python
import requests

url = "https://example.mydomain.com/api/update-records-by-matching-values"

payload = {
    "blocId": "a1489634-4009-4cc0-8a65-9965f5a1bea7",
    "fieldsToUpdate": {
        "field_number_2": "Updated Value"
    },
    "searchItems": {
        "field_number_1": "Rafael"
    }
}

headers = {
    "Authorization": "Bearer [AUTHTOKEN]",
    "Content-Type": "application/json"
}

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://manual.blocworx.com/blocworx-api/reference/api-reference/updating-data.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.