Replace Contact Data

curl --request PUT \
  --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.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  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 => "PUT",
  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("PUT", 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.put("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::Put.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>"
  ]
}

PUT

contacts

{phoneNumber}

data

Replace Contact Data

curl --request PUT \
  --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.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  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 => "PUT",
  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("PUT", 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.put("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::Put.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 to store the complete state that another system should find the next time the caller contacts you. For example, Five9 can save a conversation ID, routing status, or handoff details against the caller’s phone number. The data is scoped to your organization and the phone number. If the number does not belong to a contact yet, Simple creates a contact so the stored state is visible in the dashboard. 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 PUT 'https://api.usesimple.ai/api/v1/contacts/%2B14155550100/data' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "five9ConversationId": "conv-48291",
      "routingStatus": "awaiting_follow_up",
      "preferredLanguage": "en"
    },
    "ttlSeconds": 86400
  }'

The response contains the normalized phone number, the stored object, its revision, and expiration metadata:

{
  "phoneNumber": "+14155550100",
  "data": {
    "five9ConversationId": "conv-48291",
    "routingStatus": "awaiting_follow_up",
    "preferredLanguage": "en"
  },
  "revision": 1,
  "ttlSeconds": 86400,
  "expiresAt": "2026-08-05T12:00:00.000Z"
}

Data does not expire unless you provide ttlSeconds. When supplied, it must be an integer from 60 seconds through 90 days. The serialized data object may be at most 64 KiB. 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 replaced.

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

Replace Contact Data

Authorizations

Path Parameters

Body

Response