Create or update a record

curl --request POST \
  --url https://api.custral.com/v1/records/{object}/upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "matchOn": "email",
  "fields": {
    "email": "jane@acme.com",
    "full_name": "Jane Doe"
  },
  "createFields": {
    "status": "Lead"
  }
}
'

import requests

url = "https://api.custral.com/v1/records/{object}/upsert"

payload = {
    "matchOn": "email",
    "fields": {
        "email": "jane@acme.com",
        "full_name": "Jane Doe"
    },
    "createFields": { "status": "Lead" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    matchOn: 'email',
    fields: {email: 'jane@acme.com', full_name: 'Jane Doe'},
    createFields: {status: 'Lead'}
  })
};

fetch('https://api.custral.com/v1/records/{object}/upsert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.custral.com/v1/records/{object}/upsert",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'matchOn' => 'email',
    'fields' => [
        'email' => 'jane@acme.com',
        'full_name' => 'Jane Doe'
    ],
    'createFields' => [
        'status' => 'Lead'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.custral.com/v1/records/{object}/upsert"

	payload := strings.NewReader("{\n  \"matchOn\": \"email\",\n  \"fields\": {\n    \"email\": \"jane@acme.com\",\n    \"full_name\": \"Jane Doe\"\n  },\n  \"createFields\": {\n    \"status\": \"Lead\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.custral.com/v1/records/{object}/upsert")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"matchOn\": \"email\",\n  \"fields\": {\n    \"email\": \"jane@acme.com\",\n    \"full_name\": \"Jane Doe\"\n  },\n  \"createFields\": {\n    \"status\": \"Lead\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.custral.com/v1/records/{object}/upsert")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"matchOn\": \"email\",\n  \"fields\": {\n    \"email\": \"jane@acme.com\",\n    \"full_name\": \"Jane Doe\"\n  },\n  \"createFields\": {\n    \"status\": \"Lead\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "<string>",
    "action": "created",
    "ignoredFields": [
      "<string>"
    ],
    "droppedRelationTargets": [
      {
        "field": "<string>",
        "dropped": 123
      }
    ]
  },
  "reqId": "req_2a1f9c8e7b6d5"
}

{
  "error": {
    "code": "validation_failed"
  },
  "reqId": "req_2a1f9c8e7b6d5"
}

{
  "error": {
    "code": "invalid_api_key"
  },
  "reqId": "req_2a1f9c8e7b6d5"
}

{
  "error": {
    "code": "insufficient_scope"
  },
  "reqId": "req_2a1f9c8e7b6d5"
}

{
  "error": {
    "code": "not_found"
  },
  "reqId": "req_2a1f9c8e7b6d5"
}

{
  "error": {
    "code": "rate_limited"
  },
  "reqId": "req_2a1f9c8e7b6d5"
}

Records

Create or update a record

Write a record by an identifying property: the record whose matchOn property holds the value in fields is updated, or created when none does. Send the same call twice and you get one record. createFields are written only when the record is created, so a first stage or owner never overwrites what people have changed since. Requires scope: records:write.

The match is exact and reads committed data, so an upsert straight after a create finds it. Two upserts of the same value at once are serialised, not duplicated. When two or more records already hold the value the call fails with match_ambiguous and writes nothing; update the one you mean by its id. matchOn must be a text, email, phone or website property (match_property_invalid otherwise), and fields must include its value (match_value_missing). Fields behave exactly as on create: unknown keys come back in ignoredFields, and an unknown option label fails with option_not_found.

POST

records

{object}

upsert

Create or update a record

curl --request POST \
  --url https://api.custral.com/v1/records/{object}/upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "matchOn": "email",
  "fields": {
    "email": "jane@acme.com",
    "full_name": "Jane Doe"
  },
  "createFields": {
    "status": "Lead"
  }
}
'

import requests

url = "https://api.custral.com/v1/records/{object}/upsert"

payload = {
    "matchOn": "email",
    "fields": {
        "email": "jane@acme.com",
        "full_name": "Jane Doe"
    },
    "createFields": { "status": "Lead" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    matchOn: 'email',
    fields: {email: 'jane@acme.com', full_name: 'Jane Doe'},
    createFields: {status: 'Lead'}
  })
};

fetch('https://api.custral.com/v1/records/{object}/upsert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.custral.com/v1/records/{object}/upsert",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'matchOn' => 'email',
    'fields' => [
        'email' => 'jane@acme.com',
        'full_name' => 'Jane Doe'
    ],
    'createFields' => [
        'status' => 'Lead'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.custral.com/v1/records/{object}/upsert"

	payload := strings.NewReader("{\n  \"matchOn\": \"email\",\n  \"fields\": {\n    \"email\": \"jane@acme.com\",\n    \"full_name\": \"Jane Doe\"\n  },\n  \"createFields\": {\n    \"status\": \"Lead\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.custral.com/v1/records/{object}/upsert")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"matchOn\": \"email\",\n  \"fields\": {\n    \"email\": \"jane@acme.com\",\n    \"full_name\": \"Jane Doe\"\n  },\n  \"createFields\": {\n    \"status\": \"Lead\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.custral.com/v1/records/{object}/upsert")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"matchOn\": \"email\",\n  \"fields\": {\n    \"email\": \"jane@acme.com\",\n    \"full_name\": \"Jane Doe\"\n  },\n  \"createFields\": {\n    \"status\": \"Lead\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "<string>",
    "action": "created",
    "ignoredFields": [
      "<string>"
    ],
    "droppedRelationTargets": [
      {
        "field": "<string>",
        "dropped": 123
      }
    ]
  },
  "reqId": "req_2a1f9c8e7b6d5"
}

{
  "error": {
    "code": "validation_failed"
  },
  "reqId": "req_2a1f9c8e7b6d5"
}

{
  "error": {
    "code": "invalid_api_key"
  },
  "reqId": "req_2a1f9c8e7b6d5"
}

{
  "error": {
    "code": "insufficient_scope"
  },
  "reqId": "req_2a1f9c8e7b6d5"
}

{
  "error": {
    "code": "not_found"
  },
  "reqId": "req_2a1f9c8e7b6d5"
}

{
  "error": {
    "code": "rate_limited"
  },
  "reqId": "req_2a1f9c8e7b6d5"
}

Authorizations

Authorization

string

header

required

A Custral secret API key (sk_…), created in Settings → Applications. Sent as Authorization: Bearer sk_…. The X-Api-Key: sk_… header is also accepted and takes precedence. Never expose a secret key in a browser.

Path Parameters

object

string

required

The target object — its id (obj_…), key, or name (e.g. contacts).

Body

application/json

matchOn

string

required

The property that identifies the record — its id, key, or name. Must be a text, email, phone, or website property, and fields must carry its value.

Example:

"email"

fields

object

required

A {property: value} map, as on create. Select and status values may be option labels.

createFields

object

A {property: value} map written only when the upsert creates the record, merged over fields; ignored when it updates one. Use it for a first stage or owner that people may change later.

name

string

An optional record name.

Response

The record's id, and whether it was created or updated.

data

object

Show child attributes

reqId

string

A per-request id (req_…). Quote it to support when reporting a problem.

Example:

"req_2a1f9c8e7b6d5"

Introduction

Endpoints

Embeds & real-time

Create or update a record

Authorizations

Path Parameters

Body

Response