Read Contact Data

curl --request GET \
  --url https://api.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data \
  --header 'Authorization: <api-key>'

import requests

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

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

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 => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

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

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

	fmt.Println(string(body))

}

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::Get.new(url)
request["Authorization"] = '<api-key>'

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>"
  ]
}

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

GET

contacts

{phoneNumber}

data

Read Contact Data

curl --request GET \
  --url https://api.prod.usesimple.ai/api/v1/contacts/{phoneNumber}/data \
  --header 'Authorization: <api-key>'

import requests

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

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

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 => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

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

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

	fmt.Println(string(body))

}

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::Get.new(url)
request["Authorization"] = '<api-key>'

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>"
  ]
}

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

Use this endpoint to retrieve state that Simple or another connected system previously stored for a caller. This lets a workflow such as Five9 look up context from an earlier touch using the caller’s phone number. Data is scoped to your organization. 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 'https://api.usesimple.ai/api/v1/contacts/%2B14155550100/data' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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

{
  "phoneNumber": "+14155550100",
  "data": {
    "five9ConversationId": "conv-48291",
    "routingStatus": "awaiting_follow_up"
  },
  "revision": 3,
  "ttlSeconds": null,
  "expiresAt": null
}

Records have no expiry by default. A record with an expired TTL, or a record that has been deleted, is treated as missing and returns 404. The endpoint returns 401 when authentication fails, 404 when no current data exists for the phone number, and 422 when the phone number 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.

Response

Current contact data.

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

Read Contact Data

Authorizations

Path Parameters

Response