Update a person by UUID (partial update — only provided fields are written).
curl --request PUT \
--url https://production-api.joinrings.com/v1/persons/{person_uuid} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"city": "<string>",
"country_code": "<string>",
"custom_fields": {},
"description": "<string>",
"email": "<string>",
"email_3": "<string>",
"email_4": "<string>",
"email_5": "<string>",
"facebook_url": "<string>",
"first_name": "<string>",
"job_title": "<string>",
"last_name": "<string>",
"linkedin_url": "<string>",
"logo_url": "<string>",
"mobile_phone": "<string>",
"name": "<string>",
"phone": "<string>",
"secondary_email": "<string>",
"secondary_phone": "<string>",
"state_code": "<string>",
"twitter_url": "<string>",
"website": "<string>"
}
'import requests
url = "https://production-api.joinrings.com/v1/persons/{person_uuid}"
payload = {
"city": "<string>",
"country_code": "<string>",
"custom_fields": {},
"description": "<string>",
"email": "<string>",
"email_3": "<string>",
"email_4": "<string>",
"email_5": "<string>",
"facebook_url": "<string>",
"first_name": "<string>",
"job_title": "<string>",
"last_name": "<string>",
"linkedin_url": "<string>",
"logo_url": "<string>",
"mobile_phone": "<string>",
"name": "<string>",
"phone": "<string>",
"secondary_email": "<string>",
"secondary_phone": "<string>",
"state_code": "<string>",
"twitter_url": "<string>",
"website": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
city: '<string>',
country_code: '<string>',
custom_fields: {},
description: '<string>',
email: '<string>',
email_3: '<string>',
email_4: '<string>',
email_5: '<string>',
facebook_url: '<string>',
first_name: '<string>',
job_title: '<string>',
last_name: '<string>',
linkedin_url: '<string>',
logo_url: '<string>',
mobile_phone: '<string>',
name: '<string>',
phone: '<string>',
secondary_email: '<string>',
secondary_phone: '<string>',
state_code: '<string>',
twitter_url: '<string>',
website: '<string>'
})
};
fetch('https://production-api.joinrings.com/v1/persons/{person_uuid}', 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://production-api.joinrings.com/v1/persons/{person_uuid}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'city' => '<string>',
'country_code' => '<string>',
'custom_fields' => [
],
'description' => '<string>',
'email' => '<string>',
'email_3' => '<string>',
'email_4' => '<string>',
'email_5' => '<string>',
'facebook_url' => '<string>',
'first_name' => '<string>',
'job_title' => '<string>',
'last_name' => '<string>',
'linkedin_url' => '<string>',
'logo_url' => '<string>',
'mobile_phone' => '<string>',
'name' => '<string>',
'phone' => '<string>',
'secondary_email' => '<string>',
'secondary_phone' => '<string>',
'state_code' => '<string>',
'twitter_url' => '<string>',
'website' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$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://production-api.joinrings.com/v1/persons/{person_uuid}"
payload := strings.NewReader("{\n \"city\": \"<string>\",\n \"country_code\": \"<string>\",\n \"custom_fields\": {},\n \"description\": \"<string>\",\n \"email\": \"<string>\",\n \"email_3\": \"<string>\",\n \"email_4\": \"<string>\",\n \"email_5\": \"<string>\",\n \"facebook_url\": \"<string>\",\n \"first_name\": \"<string>\",\n \"job_title\": \"<string>\",\n \"last_name\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"logo_url\": \"<string>\",\n \"mobile_phone\": \"<string>\",\n \"name\": \"<string>\",\n \"phone\": \"<string>\",\n \"secondary_email\": \"<string>\",\n \"secondary_phone\": \"<string>\",\n \"state_code\": \"<string>\",\n \"twitter_url\": \"<string>\",\n \"website\": \"<string>\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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.put("https://production-api.joinrings.com/v1/persons/{person_uuid}")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"city\": \"<string>\",\n \"country_code\": \"<string>\",\n \"custom_fields\": {},\n \"description\": \"<string>\",\n \"email\": \"<string>\",\n \"email_3\": \"<string>\",\n \"email_4\": \"<string>\",\n \"email_5\": \"<string>\",\n \"facebook_url\": \"<string>\",\n \"first_name\": \"<string>\",\n \"job_title\": \"<string>\",\n \"last_name\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"logo_url\": \"<string>\",\n \"mobile_phone\": \"<string>\",\n \"name\": \"<string>\",\n \"phone\": \"<string>\",\n \"secondary_email\": \"<string>\",\n \"secondary_phone\": \"<string>\",\n \"state_code\": \"<string>\",\n \"twitter_url\": \"<string>\",\n \"website\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://production-api.joinrings.com/v1/persons/{person_uuid}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"city\": \"<string>\",\n \"country_code\": \"<string>\",\n \"custom_fields\": {},\n \"description\": \"<string>\",\n \"email\": \"<string>\",\n \"email_3\": \"<string>\",\n \"email_4\": \"<string>\",\n \"email_5\": \"<string>\",\n \"facebook_url\": \"<string>\",\n \"first_name\": \"<string>\",\n \"job_title\": \"<string>\",\n \"last_name\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"logo_url\": \"<string>\",\n \"mobile_phone\": \"<string>\",\n \"name\": \"<string>\",\n \"phone\": \"<string>\",\n \"secondary_email\": \"<string>\",\n \"secondary_phone\": \"<string>\",\n \"state_code\": \"<string>\",\n \"twitter_url\": \"<string>\",\n \"website\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"rings_updated_at": 123,
"uuid": "<string>",
"email_slot": "<string>"
}Person
Update a person
Fields omitted from the request body are left unchanged on the existing record. Returns 404 if the person UUID is not visible to your tenant. Returns the UUID and updated rings_updated_at timestamp on success.
email adds an address rather than replacing one: it goes to the person’s
next free email slot, and the response’s email_slot says which. The other
four slots are still set by name (secondary_email, email_3..email_5),
so an address in one of those can be corrected directly; slot 1 cannot be
replaced through this API.
PUT
/
v1
/
persons
/
{person_uuid}
Update a person by UUID (partial update — only provided fields are written).
curl --request PUT \
--url https://production-api.joinrings.com/v1/persons/{person_uuid} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"city": "<string>",
"country_code": "<string>",
"custom_fields": {},
"description": "<string>",
"email": "<string>",
"email_3": "<string>",
"email_4": "<string>",
"email_5": "<string>",
"facebook_url": "<string>",
"first_name": "<string>",
"job_title": "<string>",
"last_name": "<string>",
"linkedin_url": "<string>",
"logo_url": "<string>",
"mobile_phone": "<string>",
"name": "<string>",
"phone": "<string>",
"secondary_email": "<string>",
"secondary_phone": "<string>",
"state_code": "<string>",
"twitter_url": "<string>",
"website": "<string>"
}
'import requests
url = "https://production-api.joinrings.com/v1/persons/{person_uuid}"
payload = {
"city": "<string>",
"country_code": "<string>",
"custom_fields": {},
"description": "<string>",
"email": "<string>",
"email_3": "<string>",
"email_4": "<string>",
"email_5": "<string>",
"facebook_url": "<string>",
"first_name": "<string>",
"job_title": "<string>",
"last_name": "<string>",
"linkedin_url": "<string>",
"logo_url": "<string>",
"mobile_phone": "<string>",
"name": "<string>",
"phone": "<string>",
"secondary_email": "<string>",
"secondary_phone": "<string>",
"state_code": "<string>",
"twitter_url": "<string>",
"website": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
city: '<string>',
country_code: '<string>',
custom_fields: {},
description: '<string>',
email: '<string>',
email_3: '<string>',
email_4: '<string>',
email_5: '<string>',
facebook_url: '<string>',
first_name: '<string>',
job_title: '<string>',
last_name: '<string>',
linkedin_url: '<string>',
logo_url: '<string>',
mobile_phone: '<string>',
name: '<string>',
phone: '<string>',
secondary_email: '<string>',
secondary_phone: '<string>',
state_code: '<string>',
twitter_url: '<string>',
website: '<string>'
})
};
fetch('https://production-api.joinrings.com/v1/persons/{person_uuid}', 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://production-api.joinrings.com/v1/persons/{person_uuid}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'city' => '<string>',
'country_code' => '<string>',
'custom_fields' => [
],
'description' => '<string>',
'email' => '<string>',
'email_3' => '<string>',
'email_4' => '<string>',
'email_5' => '<string>',
'facebook_url' => '<string>',
'first_name' => '<string>',
'job_title' => '<string>',
'last_name' => '<string>',
'linkedin_url' => '<string>',
'logo_url' => '<string>',
'mobile_phone' => '<string>',
'name' => '<string>',
'phone' => '<string>',
'secondary_email' => '<string>',
'secondary_phone' => '<string>',
'state_code' => '<string>',
'twitter_url' => '<string>',
'website' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$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://production-api.joinrings.com/v1/persons/{person_uuid}"
payload := strings.NewReader("{\n \"city\": \"<string>\",\n \"country_code\": \"<string>\",\n \"custom_fields\": {},\n \"description\": \"<string>\",\n \"email\": \"<string>\",\n \"email_3\": \"<string>\",\n \"email_4\": \"<string>\",\n \"email_5\": \"<string>\",\n \"facebook_url\": \"<string>\",\n \"first_name\": \"<string>\",\n \"job_title\": \"<string>\",\n \"last_name\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"logo_url\": \"<string>\",\n \"mobile_phone\": \"<string>\",\n \"name\": \"<string>\",\n \"phone\": \"<string>\",\n \"secondary_email\": \"<string>\",\n \"secondary_phone\": \"<string>\",\n \"state_code\": \"<string>\",\n \"twitter_url\": \"<string>\",\n \"website\": \"<string>\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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.put("https://production-api.joinrings.com/v1/persons/{person_uuid}")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"city\": \"<string>\",\n \"country_code\": \"<string>\",\n \"custom_fields\": {},\n \"description\": \"<string>\",\n \"email\": \"<string>\",\n \"email_3\": \"<string>\",\n \"email_4\": \"<string>\",\n \"email_5\": \"<string>\",\n \"facebook_url\": \"<string>\",\n \"first_name\": \"<string>\",\n \"job_title\": \"<string>\",\n \"last_name\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"logo_url\": \"<string>\",\n \"mobile_phone\": \"<string>\",\n \"name\": \"<string>\",\n \"phone\": \"<string>\",\n \"secondary_email\": \"<string>\",\n \"secondary_phone\": \"<string>\",\n \"state_code\": \"<string>\",\n \"twitter_url\": \"<string>\",\n \"website\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://production-api.joinrings.com/v1/persons/{person_uuid}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"city\": \"<string>\",\n \"country_code\": \"<string>\",\n \"custom_fields\": {},\n \"description\": \"<string>\",\n \"email\": \"<string>\",\n \"email_3\": \"<string>\",\n \"email_4\": \"<string>\",\n \"email_5\": \"<string>\",\n \"facebook_url\": \"<string>\",\n \"first_name\": \"<string>\",\n \"job_title\": \"<string>\",\n \"last_name\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"logo_url\": \"<string>\",\n \"mobile_phone\": \"<string>\",\n \"name\": \"<string>\",\n \"phone\": \"<string>\",\n \"secondary_email\": \"<string>\",\n \"secondary_phone\": \"<string>\",\n \"state_code\": \"<string>\",\n \"twitter_url\": \"<string>\",\n \"website\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"rings_updated_at": 123,
"uuid": "<string>",
"email_slot": "<string>"
}Authorizations
Path Parameters
Body
application/json
City name, e.g. 'Los Angeles'.
ISO 3166-1 alpha-2 country code, e.g. 'US'. Not a country name.
Person custom field values keyed by field id from GET /v1/persons/custom-fields; null clears a field. Only the fields present are written. Values use the shapes described on the person response; an invalid value fails the request with 400 naming the field, before anything is written.
Full ISO 3166-2 subdivision code including the country prefix — 'US-CA', not 'CA' and not 'California'. This is a different vocabulary from the state filter on GET /v1/persons, which takes a name or a country-scoped code. A value that is not a valid code is stored as given but will not resolve to a state on read.
Response
200 - application/json
Response body for person create/update.
Which of the five email slots the submitted email was written to: email, secondary_email, email_3, email_4 or email_5. An address sent for a person who already exists is added to their next free slot rather than overwriting slot 1, so this will not always be email. null when no email was submitted, when the person already held that address, or when all five slots were already full.