Merge Contact Data

curl --request PATCH \
  --url https://api.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "data": {},
  "ttlSeconds": 3888030
}
'

import requests

url = "https://api.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data"

payload = {
    "data": {},
    "ttlSeconds": 3888030
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({data: {}, ttlSeconds: 3888030})
};

fetch('https://api.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data', 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.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        
    ],
    'ttlSeconds' => 3888030
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "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.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data"

	payload := strings.NewReader("{\n  \"data\": {},\n  \"ttlSeconds\": 3888030\n}")

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

	req.Header.Add("Authorization", "<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.patch("https://api.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {},\n  \"ttlSeconds\": 3888030\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {},\n  \"ttlSeconds\": 3888030\n}"

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

{
  "phoneNumber": "<string>",
  "data": {},
  "revision": 2,
  "ttlSeconds": 123,
  "expiresAt": "2023-11-07T05:31:56Z"
}

{
  "status": "<string>",
  "success": true,
  "error": "<string>",
  "errors": [
    "<string>"
  ]
}

{
  "status": "<string>",
  "success": true,
  "error": "<string>",
  "errors": [
    "<string>"
  ]
}

PATCH

contacts

{phoneNumber}

data

Merge Contact Data

curl --request PATCH \
  --url https://api.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "data": {},
  "ttlSeconds": 3888030
}
'

import requests

url = "https://api.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data"

payload = {
    "data": {},
    "ttlSeconds": 3888030
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({data: {}, ttlSeconds: 3888030})
};

fetch('https://api.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data', 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.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        
    ],
    'ttlSeconds' => 3888030
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "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.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data"

	payload := strings.NewReader("{\n  \"data\": {},\n  \"ttlSeconds\": 3888030\n}")

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

	req.Header.Add("Authorization", "<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.patch("https://api.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {},\n  \"ttlSeconds\": 3888030\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {},\n  \"ttlSeconds\": 3888030\n}"

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

{
  "phoneNumber": "<string>",
  "data": {},
  "revision": 2,
  "ttlSeconds": 123,
  "expiresAt": "2023-11-07T05:31:56Z"
}

{
  "status": "<string>",
  "success": true,
  "error": "<string>",
  "errors": [
    "<string>"
  ]
}

{
  "status": "<string>",
  "success": true,
  "error": "<string>",
  "errors": [
    "<string>"
  ]
}

Use this endpoint when an external system needs to update only part of the state stored against a caller’s phone number. PATCH merges top-level fields into the existing object without replacing unrelated fields. Set a field to null to delete that field. If no data exists yet, the patch starts with an empty object. A PATCH without ttlSeconds preserves the existing expiration; provide a new value to replace it. The data is scoped to your organization and the phone number. A previously unknown number gets a contact automatically. US numbers can be formatted or sent as digits. Non-US numbers must include the + country code. URL-encode the + when it appears in the path.

curl -X PATCH 'https://api.usesimple.ai/api/v1/contacts/14155550100/data' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "routingStatus": "completed",
      "five9ConversationId": null
    }
  }'

For example, if the stored object is {"five9ConversationId":"conv-48291","routingStatus":"queued"}, the request above leaves {"routingStatus":"completed"}. The response contains the normalized phone number, the merged object, its revision, and expiration metadata:

{
  "phoneNumber": "+14155550100",
  "data": {
    "routingStatus": "completed"
  },
  "revision": 2,
  "ttlSeconds": null,
  "expiresAt": null
}

The serialized data object may be at most 64 KiB. When supplied, ttlSeconds must be an integer from 60 seconds through 90 days. Without an explicit TTL, a record has no expiry by default or keeps its current expiry when patching an existing record. The endpoint returns 401 when authentication fails and 422 when the phone number or request body is invalid.

Authorizations

Authorization

string

header

required

Path Parameters

phoneNumber

string

required

The caller's phone number. US numbers may be formatted or sent as digits; non-US numbers must include the + country code.

Body

application/json

data

object

required

The JSON object to store. Its serialized UTF-8 size may not exceed 64 KiB.

ttlSeconds

integer

Optional expiration in seconds. Omit for no expiry; allowed values range from 60 seconds through 90 days.

Required range: 60 <= x <= 7776000

Response

Contact data merged.

phoneNumber

string

required

The normalized phone number in E.164 format.

data

object

required

The stored JSON object.

revision

integer

required

The revision number of this value.

Required range: x >= 1

ttlSeconds

integer | null

required

Remaining TTL in seconds, or null when the record has no expiry.

expiresAt

string<date-time> | null

required

Expiration timestamp in UTC, or null when the record has no expiry.

⌘I

API Documentation

Simple Example

Calls

Contacts

Interactions

Call Tags

Call Notes

Feedback

Agents

Numbers

Voices

Custom Data

Webhooks

Merge Contact Data

Authorizations

Path Parameters

Body

Response