---
title: "Working with Records"
slug: "working-with-records"
updated: 2023-09-21T19:03:26Z
published: 2023-09-21T19:03:26Z
canonical: "docs.agilenow.io/working-with-records"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agilenow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with Records

The examples in this section use REST API resources to create, retrieve, update, and delete records, along with other record-related operations.

## Get `{Entity name}`

Get a record of the method. The method contains two parameters `Id` and `Name`. The method returns one record of the entity.

If the `Id` field value is matched multiple times, then a `400` error is reported (Errors/Multiple Rows), and the error record is returned.

If the value in the `Name` field value does not match, a `404` error is reported (Errors/Invalid Field), and the error record is returned.

- REST API / Tag - `{Entity plural}` >> Departments
- Scope - `{Entity name}:Read` >> Department:Read
- Responses - `200, 400, 401, 403, 404, 500`
- Name - `Get{Entity name}` >> GetDepartment
- Input parameters - Id, Name
- Output parameters - Result {`Entity name record`}
- URL - `/{Module}/rest/{Entity plural}/`
- URL Path - /
- HTTP Method - `GET`
- Example - request `GET` /OpenApi/rest/Departments/XYZ123?Name=ExternalId >> `Result`

## List `{Entity plural}`

Use the List `Name` resource to execute a query that includes information that returns all the results in a single response, or if needed, returns part of the results and an identifier used to retrieve the remaining results. More information of query parameters - [Search query parameters](/v1/docs/api-search-query-parameters)

- REST API / Tag - `{Entity plural}` >> Departments
- Scope - `{Entity name}:Read` >> Department:Read
- Responses - `200, 400, 401, 403, 500`
- Name - `List{Entity plural}` >> ListDepartments
- Input parameters - Fields, Filters, Orders, StartIndex, PageSize
- Output parameters - Result {`Entity plural`}
- URL - `/{Module}/rest/{Entity plural}/`
- URL Path - /
- HTTP Method - `GET`
- Example - request `GET` /OpenApi/rest/Departments/? >> `Result`

## Upsert`{Entity name}`

Insert or Update (Upsert) a record using an `ExternalId` or `Id` field value.

### Id

If the `Id` field value is not matched, then a `404` error is reported (Errors/Invalid Identifier), and the error record is returned. You cannot change `Id` field value.

### ExternalId

If the `ExternalId` field value is not empty and `Id` field value is empty, action try update or insert record according `ExternalId` field value.

### Create a new record

If the value in the `ExternalId` and `Id` fields are empty then action insert a new record according input parameter entity record structure (`Entity name`Post).

### Input parameter

The input parameter must be used in the entity record structure (`Entity name`Post) inside the `FieldType` parameter in the foreign key fields. Method returns the entity record structure (`Entity name`) within `AbstractText` and `AbstractLong` records in foreign key fields.

- REST API / Tag - `{Entity plural}` >> Departments
- Scope - `{Entity plural}:Create and Update` >> Department:Create and Update
- Responses - `200, 400, 401, 403, 500`
- Name - `Upsert{Entity name}` >> UpsertDepartment
- Input parameters - `{Entity name}` (`Entity name`Post) >> Department
- Output parameters - Result (`Entity name`)
- URL - `/{Module}/rest/{Entity plural}/`
- URL Path - /Upsert
- HTTP Method - `POST`
- Example - request `POST` /OpenApi/rest/Departments/Upsert  Data[`DepartmentPost`] >> `Result`

## Create`{Entity name}`

Use the `Entity name`Post object resource to create new records. You supply the required field values in the request data, and then use the POST method of the resource. The response body will contain the full `Entity name` object of the created record if the call is successful.

The input parameter must be used in the entity record structure (`Entity name`Post) inside the `FieldType` parameter in the foreign key fields. Method returns the entity record structure (`Entity name`) within `AbstractText` and `AbstractLong` records in foreign key fields.

- REST API / Tag - `{Entity plural}` >> Departments
- Scope - `{Entity name}:Create` >> Department:Create
- Responses - `200, 400, 401, 403, 500`
- Name - `Create{Entity name}` >> CreateDepartment
- Input parameters - `{Entity name}` (`Entity name`Post) >> Department
- Output parameters - Result (`Entity name`)
- URL - `/{Module}/rest/{Entity plural}/`
- URL Path - /
- HTTP Method - `POST`
- Example - request `POST` /OpenApi/rest/Departments/  Data[`DepartmentPost`] >> `Result`

## Update`{Entity name}`

You use the `Entity name`Post object resource to update records. Provide the updated record information in your request data and use the PUT method of the resource with a specific record ID to update that record. The response body will contain the full `Entity name` object of the updated record if the call is successful.

### Update a record using an `ExternalId` or `Id` field value.

If the `Name` field value is matched multiple times, then a `400` error is reported, and the only one row is returned.

If the value in the `Name` field does not match, a `404` error is reported, and the error record is returned.

The input parameter must be used in the entity record structure (`Entity name`Post) inside the `FieldType` parameter in the foreign key fields. Method returns the entity record structure (`Entity name`) within `AbstractText` and `AbstractLong` records in foreign key fields.

- REST API / Tag - `{Entity plural}` >> Departments
- Scope - `{Entity name}:Update` >> Department:Update
- Responses - `200, 400, 401, 403, 404, 500`
- Name - `Update{Entity name}` >> UpdateDepartment
- Input parameters - Id, Name, `{Entity name}` (`Entity name`Post) >> Department
- Output parameters - Result (`Entity name`)
- URL - `/{Module}/rest/{Entity plural}/`
- URL Path - /
- HTTP Method - `PUT`
- Example - request `PUT` /OpenApi/rest/Departments/XYZ123?Name=ExternalId  Data[`DepartmentPost`] >> `Result`

## Patch `{Entity plural}`

Use patch to insert multiple records and / or update multiple records using record indentifer or external identifier.

### Extra

If there is need to do extra validations for the records these must be provded Inside the `ListValidation list` parameter

### IsFullValidation

If the value is true, the data quality of all fields are checked. This has an effect on performance.

### RecordList

#### Id

If the `Id` field value is not matched, then a `404` error is reported (Errors/Invalid Identifier), and the error record is returned. You cannot change `Id` field value.

#### ExternalId

If the `ExternalId` field value is not empty and `Id` field value is empty, action try update or insert record according `ExternalId` field value.

#### Create a new record

If the value in the `ExternalId` and `Id` fields are empty then action insert a new record according input parameter entity record structure (`Entity plular`Post).

### Input parameter

The input parameter must be used in the entity record structure (`Entity plular`Post) inside the `FieldType list` parameter in the foreign key fields. Method returns the entity record structure (`Entity plular`) within `AbstractText` and `AbstractLong` records in foreign key fields.

- REST API / Tag - `{Entity plural}` >> Departments
- Scope - `{Entity list}:Create and Update` >> Departments:Create and Update
- Responses - `200, 400, 401, 403, 500`
- Name - `Patch{Entity plural}` >> PatchDepartments
- Input parameters - `{Entity plural}` (`Entity plural`Post) >> Departments
- Output parameters - Result (`Entity list`)
- URL - `/{Module}/rest/{Entity plural}/`
- URL Path - /Patch
- HTTP Method - `POST`
- Example - request `Patch` /OpenApi/rest/Departments/Patch  Data[`DepartmenstPost`] >> `Result`

## Delete`{Entity name}`

Use the query string resource to delete record(s). The method contains two parameters `Id` and `Name`. Specify the record ID and use the DELETE method of the resource to delete a record(s).

### Delete a record using an `ExternalId` or `Id` field value.

If the value in the `Name` field value does not match, a `404` error is reported (Errors/Invalid Field), and the error record is returned.

- REST API / Tag - `{Entity plural}` >> Departments
- Scope - `{Entity name}:Delete` >> Department:Delete
- Responses - `200, 400, 401, 403, 404, 500`
- Name - `Delete{Entity name}` >> DeleteDepartment
- Input parameters - Id, Name
- Output parameters - Result {`JValue array`}
- URL - `/{Module}/rest/{Entity plural}/`
- URL Path - /
- HTTP Method - `DELETE`
- Example - request `DELETE` /OpenApi/rest/Departments/XYZ123?Name=ExternalId >> `Result`