Create a record

Use this REST endpoint to create new records. You must supply all the required field values in the request body and send it as a POST HTTP method. You can submit a single entity record or a list of records to be created all at once.

JSON Format:

curl POST 'https://{domain}/api/3.0/entity/{entity_name}'
 -H 'Content-Type: application/json'
 -H 'Accept: application/json'
 -H 'Authorization: Bearer {access_token}'
 -d '{record(s) in JSON format}'

XML data format:

curl POST 'https://{domain}/api/3.0/entity/{entity_name}'
  -H 'Content-Type: application/xml'
  -H 'Accept: application/xml'
  -H 'Authorization: Bearer {access_token}'
  -d '{record(s) in XML format}'

Request

entity_name string Required

Use the entity’s API name in the REST resource path to specify the type of record you want to create.

Request Body

JSONdata string Required

Provide the entity data in JSON or XML format. The payload may represent a single record or an array of records. For optimal performance, we recommend limiting the number of records to fewer than 1,000.

Attention: The body payload cannot exceed 20 MB in size.

Example

curl POST 'https://{domain}/api/3.0/entity/contact'
 -H 'Content-Type: application/json'
 -H 'Accept: application/json'
 -H 'Authorization: Bearer {access_token}'
 -d '{
       "FirstName": "Sam",
       "LastName": "Davison",
       "Email": "s.davison@company.com"
     }'

Successful Response

HTTP 201 Created

{
   "id": "00100000000001F0001",
   "success": true,
   "errors": []
}

If your request payload contains an array of entities, the response will also be an array. Each item (ID) in the response corresponds to its matching record in the original payload, in the same order.

Failed Response

HTTP 406 Not Acceptable

{
    "errors": [
        {
            "code": "Missing_Field",
            "fieldName": "Name",
            "message": "You must enter a value."
        }
    ],
    "id": null,
    "success": false
}

The error message may include a property name, indicating which Entity Field the error is associated with.

Note: If the payload is an array of entity records, the response can include a collection of successfully saved items (with their IDs) and any items that failed to save (with corresponding error messages).

Related Operations

Need to insert or update in a single call? See Upsert a record. Upsert uses PUT with a unique field (such as Email or ExternalId) and either creates a new record or updates a matching one.
Plan to update the new record later with safety against concurrent writes? See Update a Record — Optimistic Concurrency for how to use the ETag response header with If-Match on a subsequent PATCH.

Status Codes

HTTP Code	Error Code	Triggered When
201 Created	—	The record (or records) was created.
202 Accepted	—	Bulk create: some records succeeded and some failed. The response body indicates which.
400 Bad Request	`PAYLOAD_MISSING`	The request body was empty or could not be parsed.
404 Not Found	`INVALID_ENTITY`	The entity name in the URL does not exist.
406 Not Acceptable	—	Model validation failed (missing required field, invalid format, etc.). See Failed Response above.
413 Payload Too Large	`PAYLOAD_TOO_LARGE`	The request body exceeded the 20 MB limit.

Table of Contents