Create an entity using the Web API

Article
11/28/2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Use a POST request to send data to create an entity. You can create multiple related entities in a single operation using ‘deep insert’. You also need to know how to set values to associate a new entity to existing entities using the @odata.bind annotation.

Note

For information about how to create and update the entity metadata using the Web API, see Create and update entity definitions using the Web API.

In this topic

Basic Create

Create related entities in one operation

Associate entities on create

Create with data returned

Basic Create

This example creates a new account entity. The response OData-EntityId header contains the Uri of the created entity.

Request

POST [Organization URI]/api/data/v8.2/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

Response

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v8.2/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)

To create a new entity you must identify the valid property names and types. For all system entities and attributes, you can find this information in the topic for that entity in the Web API EntityType Reference. For custom entities or attributes, refer to the definition of that entity in the CSDL metadata document. More information: Entity types

You can create entities related to each other by defining them as navigation properties values. This is known as deep insert.

As with a basic create, the response OData-EntityId header contains the Uri of the created entity. The URIs for the related entities created aren’t returned.

For example, the following request body posted to the Account entity set will create a total of four new entities in the context of creating an account.

A contact is created because it is defined as an object property of the single-valued navigation property primarycontactid.
An opportunity is created because it is defined as an object within an array that is set to the value of a collection-valued navigation property opportunity_customer_accounts.
A task is created because it is defined an object within an array that is set to the value of a collection-valued navigation property Opportunity_Tasks.

Request

POST [Organization URI]/api/data/v8.2/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
 "name": "Sample Account",
 "primarycontactid":
 {
     "firstname": "John",
     "lastname": "Smith"
 },
 "opportunity_customer_accounts":
 [
  {
      "name": "Opportunity associated to Sample Account",
      "Opportunity_Tasks":
      [
       { "subject": "Task associated to opportunity" }
      ]
  }
 ]
}

Response

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v8.2/accounts(3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

Associate entities on create

To associate new entities to existing entities when they are created you must set the value of single-valued navigation properties using the @odata.bind annotation.

The following request body posted to the accounts entity set will create a new account associated with an existing contact with the contactid value of 00000000-0000-0000-0000-000000000001.

Request

POST [Organization URI]/api/data/v8.2/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
"name":"Sample Account",
"primarycontactid@odata.bind":"/contacts(00000000-0000-0000-0000-000000000001)"
}

Response

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v8.2/accounts(00000000-0000-0000-0000-000000000002)

Note

Associating entities this way using a collection-valued navigation property is not supported by the Web API.

Create with data returned

Note

This capability was added with December 2016 update for Dynamics 365 (online and on-premises).

You can compose your POST request so that data from the created record will be returned with a status of 201 (Created). To get his result, you must use the return=representation preference in the request headers.

To control which properties are returned, append the $select query option to the URL to the entity set. The $expand query option will be ignored if used.

When an entity is created in this way the OData-EntityId header containing the URI to the created record is not returned.

This example creates a new account entity and returns the requested data in the response.

Request

POST [Organization URI]/api/data/v8.2/accounts?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Prefer: return=representation

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

Response

HTTP/1.1 201 Created
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: return=representation
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v8.2/$metadata#accounts/$entity",
    "@odata.etag": "W/\"536530\"",
    "accountid": "d6f193fc-ce85-e611-80d8-00155d2a68de",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Sample Account",
    "createdon": "2016-09-28T22:57:53Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

Share via

Create an entity using the Web API

In this topic

Basic Create

Associate entities on create

Create with data returned

See Also

Additional resources