Import / Export

Insert or update a record with auditing

Specified table name must be in the import authorised list. See getTablesAuthorisedForImport.

POST

/gb/record/upsert/{table_name}

curl --request POST \
  --url 'https://api.catch-e.com/gb/record/upsert/{table_name}?timezone=UTC&unique_ids_must_exist_flag=yes' \
  --header 'Authorization: <api-key>' \
  --header 'Delegated-Locking-Session-Id: <string>' \
  --header 'Audit-User-Id: <string>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "colour": "blue",
    "contract_id": 101939
  },
  {
    "colour": "red",
    "contract_id": 101940,
    "radio_pin": "P123456"
  }
]
'

{
  "detail": "Unauthorized",
  "status": 401,
  "title": "Unauthorized",
  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Records to update or insert must include the primary key as part of the JSON payload.

To insert a record set the primary key to null or an unmapped ref(UUID). To update a record set the primary key to the required value or existing ref(UUID).

Mapping ref(UUID) values can be used within records. If a ref value is in a primary key and the specified record results in an insertion, the associated ref/primary key values will be mapped to gb_import_table_field_translations.

If multiple records are specified within the payload, record locks will be obtained for each record before any updates or inserts are performed. If the necessary record locks cannot be obtained, upsert will return a 423 Locked response.

This method requires the Record:Upsert permission to be associated with your role

Authorizations

Authorizationstringheaderrequired

For accessing the API a valid token must be passed in all the queries in the 'Authorization' header.

A valid token is generated by the API and returned by the /authenticate method by supplying a valid username and password.

The following syntax must be used in the 'Authorization' header :

Bearer aaaaaa/bbbbbb.ccccccc.dddddd

Path Parameters

table_namestringrequired

Table name

Maximum string length: 64

Pattern: ^[a-z0-9\_]+$

Query Parameters

timezonestringquerydefault:UTC

Timestamps in upsert records will be parsed in the specified timezone.

The timezone value can be given in several formats, none of which are case sensitive:

As a named time zone, such as 'Europe/Helsinki', 'US/Eastern', or 'MET'.
As a string indicating an offset from UTC of the form [H]H:MM, prefixed with a + or -, such as '+10:00', '-6:00', or '+05:30'. A leading zero can optionally be used for hours values less than 10;

Maximum string length: 100

Pattern: ^[a-zA-Z0-9\/\:\+\-\_]+$

unique_ids_must_exist_flagenum<string>querydefault:yes

Unique Ids specified in upsert records must exist when this flag is 'yes'.

If a specified unique id does not exist on an upsert record, a recordDoesNotExist validation exception will be generated and the upsert process will be aborted.

Available options: yes, no

Headers

Delegated-Locking-Session-Idstringheader

(Optional) Locking responsibility will be delegated to the specified Session Id.

This header enables the client to instruct the API to merely verify the presence of locks with the specified session id, but not attempt to obtain them itself. It requires the DelegatedLocking permission to be associated with your role.

Maximum string length: 32

Pattern: ^[0-9a-f]{32}

Audit-User-Idstringheader

(Optional) User Id to use for audit purposes. This header requires the Audit:UserIdOverride permission to be associated with your role.

Maximum string length: 5

Pattern: ^[1-9]{1}[0-9]*$

Body

JSON payload

itemsobject[]

Response

Records updated successfully

Still need help? Ask the team