---
title: "REST - Upsert"
canonical: "https://help.agiloft.com/space/HELP/763691019/REST+-+Upsert"
format: markdown
---
The EWUpsert operation creates a new record if no matching record exists, or updates an existing record when a match is found.

The Upsert operation combines the functionality of the Create and Update operations into a single request, making it ideal for integrations and data synchronization.

# Endpoint Reference

| Property | Value |
| --- | --- |
| **Method** | `POST` |
| **Endpoint** | `/ewws/EWUpsert` |
| **Content-Type** | `application/x-www-form-urlencoded` |
| **Authentication** | OAuth 2.0 bearer token or basic authentication with `$login` and `$password` |
| **Async Support** | Yes (`EWAsyncStatus`) |
| **Returns** | Record ID of the created or updated record |

# Request

This section contains information about the request.

## System Parameters

These parameters control how the request is processed.

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `Authorization` | ✓ | String | OAuth 2.0 bearer token. Include `Authorization: Bearer <token>` in the request header. This is the recommended authentication method. |
| `$KB` | ✓ | String | Name of the knowledgebase. |
| `$table` | ✓ | String | Target table or logical table name. |
| `$query` | ✓ | String | Search expression used to match an existing record: `<field_name>='<value>'`   
See [Matching Behavior](#matching_behavior) for more information. |
| `$login` |  | String | User login if using basic authentication. |
| `$password` |  | String | User password if using basic authentication. |
| `$lang` |  | String | Language used to resolve field names. |
| `$async` |  | Boolean | Executes the request asynchronously. |

## Record Fields

All remaining parameters represent fields in the destination table.

When a record is created, these values populate the new record.

When a record is updated, only the supplied fields are modified.

| Parameter | Type | Description |
| --- | --- | --- |
| `<field_name>` | String | Any valid field in the destination table. |
| `<linked_field>` | String | Linked record lookup value. |
| `<multivalue_field>` | String or String[] | Multi-value field values. |

## > Macro (anchor)

Matching Behavior

For the search expression in the query parameter, choose a field that has a unique value. Or supply multiple fields when no one value is unique. For example:

| Expression | Description |
| --- | --- |
| `query=external_id='SF-001234'` | Matches records on a unique external ID field. |
| `query=contract_name='Master Services Agreement - Acme Corp'` | Matches on a unique text field. |
| `query=company_name='Acme'&&contract_type='NDA'` | Matches on multiple non-unique fields. |

Before writing data, Agiloft CLM evaluates the supplied matching criteria.

| Result | Operation |
| --- | --- |
| No matching record | Creates a new record |
| One matching record | Updates the existing record |
| Multiple matching records | Returns an error |

## Example Request

```
POST /ewws/EWUpsert
Authorization: Bearer <access_token>
Content-Type: application/x-www-form-urlencoded

$KB=Demo
$table=contacts.employees
$lang=en
$query=_login='jdoe'

_login=jdoe
first_name=John
last_name=Doe
password=password
f_group=:Service Manager
teams=:Service Management Team
```

# Response

This section contains information about the response, including potential error codes.

## Example Response

```
EWREST_id='353';
```

The returned ID represents either:

- the newly created record, or
- the existing record that was updated.

## Response Codes

| Status | Description |
| --- | --- |
| **200 OK** | Existing record updated successfully. |
| **201 Created** | New record created successfully. |
| **202 Accepted** | Request accepted for asynchronous processing. |
| **400 Bad Request** | Validation or request formatting error. |
| **401 Unauthorized** | Authentication failed. |
| **403 Forbidden** | User lacks permission. |
| **404 Not Found** | Table or resource not found. |
| **409 Conflict** | Multiple matching records found or business rule conflict. |
| **500 Internal Server Error** | Unexpected server error. |

## Common Errors

| Scenario | Status | Description |
| --- | --- | --- |
| Invalid matching field | 400 | Match field does not exist or cannot be searched. |
| Multiple matching records | 409 | More than one record satisfies the supplied criteria. |
| Required field missing | 400 | A required field was omitted during record creation. |
| Invalid linked field | 400 | Linked record lookup failed. |
| Validation failure | 400 | One or more field values failed validation. |
| Permission denied | 403 | User lacks permission to create or update records. |

# Example Workflow

```
POST /EWUpsert
        │
        ▼
Evaluate matching criteria
        │
 ┌──────┴──────┐
 │             │
Match      No Match
 │             │
 ▼             ▼
Update      Create
 │             │
 └──────┬──────┘
        ▼
 Return Record ID
```

# Best Practices

- Match on a unique business identifier whenever possible.
- Avoid using mutable values (such as names or email addresses) as matching fields.
- Submit only the fields that should be created or updated.
- Use asynchronous execution for large data synchronization jobs.
- Validate incoming data before sending requests.

# Related Operations

| Operation | Description |
| --- | --- |
| **EWCreate** | Creates a new record. |
| **EWUpdate** | Updates an existing record. |
| **EWSearch** | Searches for records. |
| **EWDelete** | Deletes records. |
| **EWAsyncStatus** | Retrieves the status of asynchronous operations. |