UpsertList SOAP Operation

The upsertList operation is used to add or update one or more instances of a record type in NetSuite.

If there are multiple records, they can either be of the same record type or different record types. For example, it’s possible to add or update a customer and a contact within a single request using this operation.

The upsertList operation is similar to both the addList and updateList operations, but upsert can be run without first determining whether records exist in NetSuite. Records are identified by their external ID and their record type. If a record of the specified type with a matching external ID exists in the system, it is updated. If it does not exist, a new record is created.

Because external ID is mandatory for this operation, upsertList is supported only for records that support the external ID field. Also, this operation prohibits the passing of internal ID values.

To prevent duplicate records, you should use external IDs and the upsert and upsertList operations to add records to NetSuite.

Limitations on upsertList

• Although records of a particular type may be used in multiple integration scenarios, each record instance can only have a single external ID value. To maintain data integrity, only a single integrated application can set and update external ID values for each record type. External ID values for all records of a particular type must all come from the same external application.
• UpsertList cannot complete updates during an initialize / initializeList operation, when a record is transformed into a record of another type. In this case, upsertList only adds and does not update records.
• Updates through the upsertList operation are also subject to the same limitations as updates through the updateList operation.

Request

<soapenv:Envelope
    xmlns:xsd='http://www.w3.org/2001/XMLSchema'
    xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
    xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'
    xmlns:platformCore='urn:core_2021_2.platform.webservices.netsuite.com'
    xmlns:listRel='urn:relationships_2021_2.lists.webservices.netsuite.com'
    xmlns:listAcct='urn:accounting_2021_2.lists.webservices.netsuite.com'
    xmlns:platformMsgs='urn:messages_2021_2.platform.webservices.netsuite.com'>
    <soapenv:Header>
        <tokenPassport xsi:type='platformCore:TokenPassport'>
            <account xsi:type='xsd:string'>{{accountId}}</account>
            <consumerKey xsi:type='xsd:string'>{{consumerKey}}</consumerKey>
            <token xsi:type='xsd:string'>{{tokenId}}</token>
            <nonce xsi:type='xsd:string'>{{nonce}}</nonce>
            <timestamp xsi:type='xsd:long'>{{timestamp}}</timestamp>
            <signature algorithm='HMAC_SHA256' xsi:type='platformCore:TokenPassportSignature'>{{signature}}</signature>
        </tokenPassport>
    </soapenv:Header>
    <soapenv:Body>
        <upsertList xsi:type='platformMsgs:UpsertListRequest'>
            <record xsi:type='listRel:Customer' externalId='123456634'>
                <mobilePhone xsi:type='xsd:string'>9495448046</mobilePhone>
            </record>
            <record xsi:type='listEmp:Employee' externalId='1234566'>
                <mobilePhone xsi:type='xsd:string'>8921576269</mobilePhone>
            </record>
        </upsertList>
    </soapenv:Body>
</soapenv:Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Header>
        <platformMsgs:documentInfo
            xmlns:platformMsgs="urn:messages_2021_2.platform.webservices.netsuite.com">
            <platformMsgs:nsId>WEBSERVICES_TSTDRV2782962_0731202313540825861976297812_cdb18</platformMsgs:nsId>
        </platformMsgs:documentInfo>
    </soapenv:Header>
    <soapenv:Body>
        <upsertListResponse
            xmlns="">
            <platformMsgs:writeResponseList
                xmlns:platformMsgs="urn:messages_2021_2.platform.webservices.netsuite.com">
                <platformCore:status isSuccess="true"
                    xmlns:platformCore="urn:core_2021_2.platform.webservices.netsuite.com"/>
                    <platformMsgs:writeResponse>
                        <platformCore:status isSuccess="true"
                            xmlns:platformCore="urn:core_2021_2.platform.webservices.netsuite.com">
                            <platformCore:statusDetail>
                                <platformCore:afterSubmitFailed>false</platformCore:afterSubmitFailed>
                            </platformCore:statusDetail>
                        </platformCore:status>
                        <platformMsgs:baseRef internalId="24" externalId="123456634" type="customer" xsi:type="platformCore:RecordRef"
                            xmlns:platformCore="urn:core_2021_2.platform.webservices.netsuite.com"/>
                        </platformMsgs:writeResponse>
                        <platformMsgs:writeResponse>
                            <platformCore:status isSuccess="true"
                                xmlns:platformCore="urn:core_2021_2.platform.webservices.netsuite.com">
                                <platformCore:statusDetail>
                                    <platformCore:afterSubmitFailed>false</platformCore:afterSubmitFailed>
                                </platformCore:statusDetail>
                            </platformCore:status>
                            <platformMsgs:baseRef internalId="26" externalId="1234566" type="employee" xsi:type="platformCore:RecordRef"
                                xmlns:platformCore="urn:core_2021_2.platform.webservices.netsuite.com"/>
                            </platformMsgs:writeResponse>
                        </platformMsgs:writeResponseList>
                    </upsertListResponse>
                </soapenv:Body>
            </soapenv:Envelope>