How to Get, Create, and Update an Object on MonoSync Using the API

This document explains how to get, create, and update an object in MonoSync using the API. Before you continue, make sure you have a valid API Key generated for your tenant.

📘 Instructions

This document covers the following 4 steps:

1. Search Object (POST)

2. Create Object (POST)

3. Update Object with Specified Fields (PATCH)

4. Update Object (PUT)

You can use Postman to send HTTP requests to MonoSync.

Let’s start by creating an Object Type on MonoSync.

To create an Object Type on MonoSync, navigate to the Object Type creation page by clicking the Object Types button, then click the Create button in the upper-right corner.

Once you have navigated to the Object Type creation page, create the fields based on the fields in your HR System, then save the Object Type by clicking the Save button in the upper-right corner.

Once the Object Type has been created in MonoSync, you can continue performing operations using Postman.

1-) Search Object (POST)

To search for objects of a specific object type in MonoSync, set the HTTP method to POST, set the Request URL based on your domain and object type, and provide your search filters in the Request Body.

POST https://{{companyDomainName}}/api/v1/objects/{{ObjectTypeName}}/search?page=1&limit=1000

The request body has two main properties: filters (the search conditions to apply) and field (which fields should be returned in the response). Depending on how these are populated, the API behaves differently, as shown in the scenarios below.

Scenario 1: Filtering on a specific field

To search for objects matching a specific field value, add a condition to the filters array with a field, an operator, and a value.

{
  "filters": [
    {
      "field": "sn",
      "operator": "eq",
      "value": "Gelderd"
    }
  ],
  "field": []
}

This request only returns the object(s) whose sn field equals Gelderd.

Scenario 2: No filter provided (return the entire list)

If the filters array is left empty, no filtering condition is applied and the API returns all objects of that object type, still subject to pagination via the page and limit parameters.

{
  "filters": [],
  "field": []
}

Scenario 3: Requesting only specific fields

If you provide a list of field names in the field array, the response only includes those fields for each object instead of all the object’s fields. This is useful to reduce the response payload when you don’t need the entire object.

{
  "filters": [
    {
      "field": "sn",
      "operator": "eq",
      "value": "Gelderd"
    }
  ],
  "field": ["sAMAccountName", "cn"]
}

In this example, the data section of each returned item will only contain sAMAccountName and cn, instead of every field defined on the object type.

This API also supports pagination:

• The page query parameter specifies which page of results to retrieve.

• The limit query parameter specifies how many records will be returned per page. The maximum value you can send for limit is 10000.

• If there are no more records left for the requested page (i.e. you requested a page beyond the last one), the API returns an empty list instead of an error.

The response also includes pageCount and itemCount fields so you can track the total number of pages and items available. Keep incrementing the page parameter until the API returns an empty list to retrieve the full result set.

2-) Create Object (POST)

To create an object of a specific object type in MonoSync, set the HTTP method to POST, set the Request URL based on your domain, specify the Request Body as shown, and click the Send button.

POST https://{{companyDomainName}}/api/v1/objects/{{ObjectTypeName}}

Sample request body:

{
  "EmployeeID": "00001",
  "FirstName": "Abbey",
  "LastName": "Craig",
  "Mail": "abbet.craig@monofor.com",
  "EmployeeStartDate": "2022-09-27T12:00:00",
  "EmployeeEndDate": "2022-12-27T12:00:00"
}

Sample response (201 Created):

{
  "data": {
    "objectId": "a4d11178-75c9-483c-bf4b-d008346f792d",
    "createdDate": "2023-04-04T13:32:58.644205Z",
    "updatedDate": "0001-01-01T00:00:00"
  },
  "success": true,
  "code": 201,
  "title": "Object Create",
  "message": "Object added successfully"
}

Once the object is created in MonoSync, you can see it in the “HR Users” object list created earlier.

3-) Update Object with Specified Fields (PATCH)

To update specific fields of an object in MonoSync, set the HTTP method to PATCH, set the Request URL based on your domain, specify the Request Body as shown, and click the Send button.

PATCH https://{{companyDomainName}}/api/v1/objects/{{ObjectTypeName}}/{{ObjectPrimaryKey}}

For example, if you only want to update an object’s FirstName and LastName, you don’t need to send the entire object in the request body — only the fields you want to update. The PATCH method updates only the fields specified in the request body, leaving the rest of the object unchanged.

{
  "FirstName": "Rachana",
  "LastName": "Viktória"
}

Sample response (200 OK):

{
  "data": {
    "objectId": "a4d11178-75c9-483c-bf4b-d008346f792d",
    "createdDate": "2023-04-04T13:32:58.644205",
    "updatedDate": "2023-04-11T16:25:33.704325Z"
  },
  "success": true,
  "code": 200,
  "title": "Object Update",
  "message": "Object updated successfully"
}

4-) Update Object (PUT)

To update an entire object in MonoSync, set the HTTP method to PUT, set the Request URL based on your domain, specify the Request Body as shown, and click the Send button.

PUT https://{{companyDomainName}}/api/v1/objects/{{ObjectTypeName}}/{{ObjectPrimaryKey}}

For example, if you only want to update an object’s LastName and EmployeeEndDate, you still need to send the entire object in the request body. The PUT method replaces the entire object with the data provided in the request body.

{
  "FirstName": "Rachana",
  "LastName": "Viktória Shireen",
  "Mail": "abbet.craig@monofor.com",
  "EmployeeStartDate": "2022-08-27T12:00:00",
  "EmployeeEndDate": "2022-12-27T12:00:00"
}

Sample response (200 OK):

{
  "data": {
    "objectId": "a4d11178-75c9-483c-bf4b-d008346f792d",
    "createdDate": "2023-04-04T13:32:58.644205",
    "updatedDate": "2023-04-11T16:30:22.581565Z"
  },
  "success": true,
  "code": 200,
  "title": "Object Update",
  "message": "Object updated successfully"
}

Once the object is updated in MonoSync, you can see the changes in the “HR Users” object list created earlier.