createRecord (Client API reference)

Creates an entity record.

Syntax

Xrm.WebApi.createRecord(entityLogicalName, data).then(successCallback, errorCallback);

Parameters

Name Type Required Description
entityLogicalName String Yes Logical name of the entity you want to create. For example: "account".
data Object Yes

A JSON object defining the attributes and values for the new entity record.

See examples later in this topic to see how you can define the data object for various create scenarios.

successCallback Function No

A function to call when a record is created. An object with the following properties will be passed to identify the new record:

  • entityType: String. The entity logical name of the new record.
  • id: String. GUID of the new record.
errorCallback Function No A function to call when the operation fails. An object with the following properties will be passed:
  • errorCode: Number. The error code.
  • message: String. An error message describing the issue.

Return Value

On success, returns a promise object containing the attributes specified earlier in the description of the successCallback parameter.

Examples

These examples use the same request objects as demonstrated in Create an entity using the Web API to define the data object for creating an entity record.

Basic create

Creates a sample account record.

// define the data to create new account
var data =
    {
        "name": "Sample Account",
        "creditonhold": false,
        "address1_latitude": 47.639583,
        "description": "This is the description of the sample account",
        "revenue": 5000000,
        "accountcategorycode": 1
    }

// create account record
Xrm.WebApi.createRecord("account", data).then(
    function success(result) {
        console.log("Account created with ID: " + result.id);
        // perform operations on record creation
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

You can create entities related to each other by defining them as navigation properties values. This is known as deep insert. In this example, we will create a sample account record along with the primary contact record and an associated opportunity record.

// define data to create primary and related entity records
var data =
    {
        "name": "Sample Account",
        "primarycontactid":
        {
            "firstname": "John",
            "lastname": "Smith"
        },
        "opportunity_customer_accounts":
        [
            {
                "name": "Opportunity associated to Sample Account",
                "Opportunity_Tasks":
                [
                    { "subject": "Task associated to opportunity" }
                ]
            }
        ]
    }

// create account record
Xrm.WebApi.createRecord("account", data).then(
    function success(result) {
        console.log("Account created with ID: " + result.id);
        // perform operations on record creation
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Associate entities on creating new records

To associate new entity records to existing entity records, set the value of single-valued navigation properties using the @odata.bind annotation. However, for mobile clients in the offline mode, you cannot use the @odata.bind annotation, and instead have to pass a lookup object (logicalname and id) pointing to the target record. Here are code examples for both the scenarios:

For online scenario (connected to server)

The following example creates an account record, and associates it to an existing contact record to set the latter as the primary contact for the new account record:

var data =
    {
        "name": "Sample Account",
        "primarycontactid@odata.bind": "/contacts(465b158c-541c-e511-80d3-3863bb347ba8)"
    }

// create account record
Xrm.WebApi.createRecord("account", data).then(
    function success(result) {
        console.log("Account created with ID: " + result.id);
        // perform operations on record creation
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

For mobile offine scenario

Here is the updated sample code to create an account record, and associate it to an existing contact record to set the latter as the primary contact for the new account record from mobile clients when working in the offline mode:

var data =
    {
        "name": "Sample Account",
        "primarycontactid":
        {
            "logicalname": "contact",
            "id": "465b158c-541c-e511-80d3-3863bb347ba8"
        } 
    }

// create account record
Xrm.WebApi.offline.createRecord("account", data).then(
    function success(result) {
        console.log("Account created with ID: " + result.id);
        // perform operations on record creation
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Create an entity using the Web API

Xrm.WebApi