# Save Single or Multiple API (generated)

> Insert one row or many with the generated save single or multiple API of API Maker - one object or an array in the body, generated ids, and select or deep on the answer.

Source: https://docs.apimaker.dev/v1/docs/apis-all/generated-apis/auto-generated-save-single-or-multiple-api.html

Inserts one row (an object) or many (an array) and answers `201` with what was saved, ids included.

| | |
|---|---|
| Method | POST |
| URL | `/api/gen/admin/mysql8/inventory/customers/save-single-or-multiple` |
| Body | one object, or an array of objects |
| Query params | [select](https://docs.apimaker.dev/v1/docs/apis-all/query-params/select.html), [deep](https://docs.apimaker.dev/v1/docs/apis-all/query-params/deep.html) : applied to the answer |
| Answer | `201` and `data` : the saved row, or the array of saved rows |
| Databases | MongoDB, MySQL, MariaDB, PostgreSQL, SQL Server, Oracle, TiDB, Percona |
| Cached | no (a write ; it resets the cache of the table) |
| From code | [`g.sys.db.gen.saveSingleOrMultipleGen`](https://docs.apimaker.dev/v1/examples/sys/db/gen/saveSingleOrMultipleGen.html) |
| API id | `GEN_POST_BULK_INSERT` (groups, settings, hooks, WebSocket subscriptions) |
| The other family | [Save single or multiple as a schema API](https://docs.apimaker.dev/v1/docs/apis-all/schema-apis/auto-generated-schema-based-save-single-or-multiple-api.html) |

> **Schemaless : the data passes as it is**
>
> The generated APIs never read the [schema](https://docs.apimaker.dev/v1/docs/schema/schema.html) of the table. Nothing is converted, validated, defaulted, encrypted or numbered : what you send is what the database gets, and a filter matches the type you send (`"22"` does not match the number `22`). On MongoDB, strings which look like ObjectIds are converted. Every table has these APIs, with or without a schema ; the same operations under `/api/schema` apply the schema.

## The URL

`/api/gen/admin/mysql8/inventory/customers/save-single-or-multiple` : replace `admin` with the user path of your account, `mysql8` with your instance, `inventory` with the database and `customers` with the table. The examples use this table :

| customer_id | first_name | last_name | last_update           | pincode | isActive |
|-------------|------------|-----------|-----------------------|---------|----------|
| 1           | Bob        | lin       | 2022-11-14 04: 34: 58 | 382345  | 1        |
| 2           | Alice      | Page      | 2022-10-15 02: 10: 40 | 382346  | 1        |
| 3           | Mallory    | Brown     | 2022-09-13 03: 44: 05 | 382347  | 1        |
| 4           | Eve        | Mathly    | 2022-11-12 01: 59: 33 | 382348  | 1        |
| 5           | Eve        | Page      | 2022-11-12 01: 59: 33 | 382349  | 1        |

## One row

```text
POST /api/gen/admin/mysql8/inventory/customers/save-single-or-multiple
```

**Body**

```json
{ "first_name": "Bob", "last_name": "Lin", "pincode": 382345 }
```

**Answer**

```json
{
    "success": true,
    "statusCode": 201,
    "data": { "customer_id": 6, "first_name": "Bob", "last_name": "Lin", "pincode": 382345 }
}
```

- The primary key can be sent (`"customer_id": 27`) or left out : the database or API Maker generates it (`isAutoIncrementByDB`, `isAutoIncrementByAM`, `isAutoGenerateByAM` in the schema, `_id` on MongoDB).

## Many rows

**Body**

```json
[
    { "first_name": "Bob", "last_name": "Lin" },
    { "customer_id": 29, "first_name": "Eve", "last_name": "Page" }
]
```

- The answer is an array in the same order. Objects with and without a primary key can mix.
- Every row is checked before anything is written ; an error names the object with `dataIndex`.

## Nested objects

- On MongoDB a nested object is stored as an embedded document, as sent. It is not saved to another collection : that needs the relations of a schema and the [schema API](https://docs.apimaker.dev/v1/docs/apis-all/schema-apis/auto-generated-schema-based-save-single-or-multiple-api.html).
- On a SQL table every key must be a column.

## The answer you want

```text
POST /api/gen/admin/mysql8/inventory/customers/save-single-or-multiple?select=customer_id,first_name
POST /api/gen/admin/mysql8/inventory/customers/save-single-or-multiple?deep=[{s_key:'shipping_id',t_col:'shippings',t_key:'id'}]
```

- `select` keeps only some fields of the saved rows in the answer ; `deep` populates their relations.

## After the save

- The cache of the table is reset, subscribed WebSocket clients are notified, events with an automatic trigger on this API run, and post hooks get the saved rows in `g.res.output`.

## From your code

[`g.sys.db.gen.saveSingleOrMultipleGen`](https://docs.apimaker.dev/v1/examples/sys/db/gen/saveSingleOrMultipleGen.html) makes the same call from custom APIs, hooks, events, schedulers and test cases, with the same headers and params. Pass `true` as the second argument to get the whole [response envelope](https://docs.apimaker.dev/v1/docs/apis-all/response-format.html) instead of `data`.

## Headers

Every call takes the [request headers](https://docs.apimaker.dev/v1/docs/apis-all/header/requestHeader.html) : the tokens, `x-am-response-case`, `x-am-content-type-response` (JSON, XML, YAML…), `x-am-response-object-type: make_flat`, `x-am-cache-control`, `x-am-get-encrypted-data`, `x-am-internationalization`, `x-am-tenant-username`, `x-am-meta`.

## Errors

| Code | When |
|---|---|
| `401` | The token in `x-am-authorization` is missing or invalid. |
| `403` | No group of the API user grants this API of this table, or a field of the request. |
| `404` | The instance, database or table of the URL does not exist. |
| `400` | The query or the body is wrong : the [error messages](https://docs.apimaker.dev/v1/docs/apis-all/error-codes.html) say which key and why. |

## Related

- [All APIs at a glance](https://docs.apimaker.dev/v1/docs/apis-all/overview.html) · [Query params](https://docs.apimaker.dev/v1/docs/apis-all/query-params/query-params.html) · [Response format](https://docs.apimaker.dev/v1/docs/apis-all/response-format.html) · [Pre hooks](https://docs.apimaker.dev/v1/docs/apis-all/hooks/preHook-api.html) and [post hooks](https://docs.apimaker.dev/v1/docs/apis-all/hooks/postHook-api.html) · [Automatic caching](https://docs.apimaker.dev/v1/docs/features/automatic-caching.html)