Create or update record

📘

How to id Custom Objects

Creating Records
When a record is created, it will be automatically assigned an id. You can create your own custom ids, to match your system. For example, you could create custom object records that match the order numbers created in your online store. To assign your own custom id, use externalId. externalId is optional, and if omitted when a record is created, the record can only be retrieved using the autogenerated and assigned id field.

It is recommended to use externalId when creating records because it makes future updates easier.

Updating Records Using id or externalId
Any value in id will be ignored if there is no record matching that id. A new record will be created and given a randomly generated id. If an existing record has a matching id provided in the request body, the existing record with that same id will be updated.

When performing a POST to /customObjects/records/SCHEMA_ID_HERE:

If id being passed in MATCHES an existing record's id, and the passed-in external-id also MATCHES the externalId:

• Record is updated, neither ids are changed

If id being passed in MATCHES the id of an existing record, but externalId DOES NOT MATCH:

• a new record is created, the id being passed-in is ignored and a new id is assigned, the record is also assigned with the passed-in externalId

If id being passed in MATCHES an existing record's id, but externalId IS OMITTED:

• Record is updated, no externalId appended

If id being passed in DOES NOT MATCH any existing record id OR IS OMITTED, but externalId DOES MATCH:

• id is not updated/changed, existing record is updated

If id being passed in DOES NOT MATCH and existing record or IS OMITTED, and externalId DOES NOT MATCH or IS OMITTED:

• A new record is created, the id being passed in is ignored and a new id assigned, and the new record is also given that passed-in externalId

{
  "record": {
    "id": "this-id-is-created-on-a-new-record-and-can-not-be-updated",
    "externalId": "external-id-that-can-be-updated",
    "fields": [
      {
        "id": "my-number-field",
        "value": 100
      }
    ],
    "relationships": {
      "primary-contact": [
        14
      ]
    }
  }
}

{
    "record": {
    	"id": "test-obj-1",
    	"externalId": "test-obj-1",
        "schemaId": "6449c3f3-b68d-46d1-850b-c8aea998ce1b",
        "fields": [
            {
                "id": "my-number-field",
                "value": 100
            }
        ],
        "relationships": {
            "primary-contact": [
                "14"
            ]
        }
    }
}