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>",
  "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>",
  "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. Callers that do not have a phone number can be keyed by any other identifier, such as a chat or SIP identifier, of up to 128 characters. Simple stores those identifiers as provided and returns them unchanged in phoneNumber.

curl 'https://api.usesimple.ai/api/v1/contacts/%2B14155550100/data' \
  -H 'Authorization: Bearer YOUR_API_KEY'

The response includes the normalized phone number, stored fields at the top level, revision, and expiration metadata. If a stored key has the same name as a metadata field, the metadata value shadows the stored value in this response:

{
  "phoneNumber": "+14155550100",
  "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 caller identifier, and 422 when the identifier is invalid.

Authorizations

Authorization

string

header

required

Path Parameters

phoneNumber

string

required

The caller's phone number or other caller identifier. US numbers may be formatted or sent as digits; non-US numbers must include the + country code. Non-phone identifiers (for example chat or SIP identifiers) are accepted verbatim, up to 128 characters.

Response

Current contact data.

phoneNumber

string

required

The normalized phone number in E.164 format, or the caller identifier as provided when it is not a phone number.

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